


Techniques for Processing Data Lists in PL/I 


This manual illustrates techniques for processing simple and complex data lists. It isa 
sequel to Introduction to the List Processing Facilities of PL/I (GF20-0015) and assumes 
knowledge of that manual. Illustrative programs were processed by the PL/I (F) 
Compiler (Version 5) under control of the IBM System/360 Operating System 

(Release 18.6). 


Data lists are made up of based variable structures that contain data plus pointers 
that link the structures. List-processing techniques are useful for handling data that 
has logical complexities not conveniently represented by conventional PL/I array and 
structure representation. 


This manual is intended for the experienced programmer. 
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Copies of this and other IBM publications can be obtained through IBM branch offices. 


A form has been provided at the back of this publication for readers’ comments. If this form 
has been removed, address comments to: IBM Corporation, Technical Publications Department, 
112 East Post Road, White Plains, New York 10601. 


*reface 


his manual serves as a sequel to the companion text 
itroduction to the List Processing Facilities of PL/I 
3F 20-0015). That text describes the facilities for proc- 
ssing lists in PL/I. The present manual extends the dis- 
ussion of simple data lists to data lists of arbitrary 
omplexity and shows how to develop hierarchical collec- 
ons of subroutines and functions for manipulating such 
sts. To make the discussion as self-contained as possible, 
*view material has been included on the PL/I facilities for 
rganizing and processing lists (Chapter 1) and on the 
ssentials of subroutines and functions (Appendix 1). 
._ppendix 2 summarizes the language facilities in PL/I for 
rocessing lists. 

List-processing techniques are advantageous for orga- 
izing and manipulating data whose structure is not con- 
oniently represented with PL/I arrays and structures. 


Structured data of this type occurs in many nonnumeric 
applications, such as information storage and retrieval, 
engineering design, computer-software production, text 
editing, and artificial intelligence. 

The advanced nature of this manual requires the reader 
to be an experienced programmer who has studied the 
companion text mentioned above and who is skilled in the 
use of subroutines and functions. References to particular 
implementations of PL/I are held to a minimum, but in- 
formation on the F-level facilities for processing lists 
appears in JBM System/360: PL/I Reference Manual 
(GC28-8201) and JBM System/360 Operating System: PL/I 
(F) Programmer’s Guide (GC28-6594). A bibliography 
provides additional sources of information on list organiza- 
tions and their applications. 
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Chapter 1: Introduction 


PURPOSE AND PLAN OF THIS MANUAL 


This manual extends the discussion of list processing pre- 
sented in the companion manual Jntroduction to the 
List Processing Facilities of PL/T (GF20-0015). That 
manual describes the facilities for organizing and manipu- 
lating lists in PL/I and illustrates the advantages of lists 
over the conventional methods for organizing storage with 
arrays and structures. 

The present manual develops techniques for creating 
data lists of any desired complexity. It begins with a re- 
view of the facilities for organizing lists in PL/I and applies 
these facilities in subsequent chapters to the construction 
of data lists, which are collections of noncontiguous data 
items linked by attached address elements; the data items 
associated with a data list always appear within the body 
of the list. Techniques for processing data lists are pre- 
sented in subroutine and function form. (Appendix 1 
contains a review of PL/I facilities for subroutines and 
functions.) 

Version 5, Release 18.6 of the PL/I (F) Compiler pro- 
duced the coded examples shown as printouts in this 
manual. The encoded examples were all compiled and 
subjected to elementary machine tests to perform as in- 
tended, except for four examples that illustrate specialized 
organizations of complex data lists. These were desk- 
checked, compiled, and executed. Note, however, that 
programming efficiency, speed of execution, core storage 
utilization, etc., are frequently sacrificed in the examples 
and discussions to simplify the presentation and to im- 
prove readability. 

The program examples are purely illustrative in nature; 
no attempt was made to develop “production”’ code. 

The list-processing programmer may wish to compare 
the convenience of using subroutines and functions to 
manipulate list components against the better performance 
of inline code. 


REVIEW OF FACILITIES FOR PROCESSING LISTS IN 
PL/I 


The facilities for processing lists in PL/I deal with four 
types of variables: AREA, BASED, OFFSET, and 
POINTER, each of which is discussed in detail in the com- 
panion manual Introduction to the List Processing 
Facilities of PL/T (GF20-0015). The following discussions 
review the main characteristics of three of these variables: 
POINTER, BASED, and AREA. 


Pointer Variables 


The value of a pointer variable is an absolute address, 
which specifies the actual location of a data item in stor- 
age. Declaration of an identifier with the POINTER 
attribute establishes the identifier as a pointer variable. 


EXAMPLES: 


DECLARE 

P POINTER, 
(Q,R) POINTER EXTERNAL STATIC, 
T(S) POINTER INTERNAL, 
V(-2:2,-3:3) POINTER, 
LA, 

2 X CHARACTER(I5), 

2 Y POINTER, 
1 TABLES, 

2 1(5) POINTER, 

2 J(0:4) POINTER: 


As shown in these examples, PL/I allows pointer variables 
to be individual element variables or elements of arrays 
and structures. A pointer variable can have any storage 
class and scope, and the usual default rules for these attri- 
bute types also hold for a pointer variable. 


Obtaining Values for Pointer Variables 

A pointer variable must receive an absolute address for its 
value before the variable can be manipulated. One way of 
obtaining an absolute address for a pointer variable is 
through the built-in functions ADDR and NULL. A 
reference to the built-in function ADDR has the form: 


ADDR (argument) 


The value returned by ADDR is the absolute address of the 
specified argument. As an example, consider the assign- 
ment statement: 


P=ADDR(X): 


Assume that P is a pointer variable and X is a data variable. 
Then the reference ADDR(X) obtains the absolute address 
of the storage location allocated for X, and the statement 
assigns this absolute address as the value of pointer P. 


An argument variable in a reference to ADDR must be 
an identifier that specifies one of the following types of 
variables: | 

1. Element variable 

2. Array 

3. Element of an array 

4. Major or minor structure 

5. Element of a structure 


Tt is also possible for an element constant to appear as 
an argument of ADDR. In this case, the PL/I compiler 
creates a dummy-argument variable for the constant, and 
ADDR returns the absolute address of the dummy argu- 
ment. (See Appendix 1 for a discussion of dummy 
arguments.) 

A reference to the built-in function NULL uses no 
arguments and has the form: 


NULL 


This function returns a null address value, which does not 
identify any location in storage. A null address is used to 
clear pointer variables and to test for unallocated storage. 

Note that PL/I does not provide explicit address con- 
stants for pointer variables. 


Using Pointer Variables in Assignment Statements 


_ PL/I permits pointer variables to appear in the follow- 
ing forms of the assignment statement: 
1. element-pointer-variable=element-pointer-expression; 
2. pointer-array=element-pointer-expression; 
3. pointer-array=pointer-array ; 


Two or more variables separated by commas may appear 
on the left side of these statements to permit multiple 
assignment. An element-pointer expression on the right 
side of an assignment statement must be either an element- 
pointer variable or a function reference (built-in or 
programmer-defined) that specifies an element-pointer 
value, that is, a single absolute address. 

Assignment of an element-pointer expression to a 
pointer array causes the value of the expression to be as- 
signed to every element of the pointer array. When a 
pointer array apprears on the right side of an assignment 
statement, the number of dimensions and the bounds for 
each dimension of the array on the right must be identical 
to those of the receiving pointer array on the left. 


EXAMPLES: 


DECLARE 
(P,Q,R,T(5),V(-2:2,-3:3)) POINTER, 
1 A, 2 X CHARACTER(15), 2 Y POINTER, 
1 TABLES, 2 1(5) POINTER, 2 J(0:4) POINTER; 


The following statements illustrate possible assignments of 
pointer values that involve the above declarations: 

1. P= ADDR(A); 

. Q,R = NULL; 

. T(4), V(-2,-3) =P; 

. AY = T(4); 

. TABLES. I, TABLES.J = NULL; 

. T= TABLES]; 


Nm BW ND = 


Statements 2,3, and 5 perform multiple assignments. The 
last three statements show name qualification applied to 
pointer variables. 


Using Pointer Variables in Operational Expressions 


PL/I allows only two operators to use pointer variables as 
operands: the comparison operators equal (=) and not 
equal ("1=). As a result of this restriction, arithmetic 
operations cannot be performed on absolute addresses. 


EXAMPLES: _ 
Assume that A and B are arithmetic variables and that 


P,Q,R,S, and T are pointer variables; then the following 
statements contain permissible uses of pointer variables as 


operands. 
1. If P=NULL THEN GO TO L; 
2. A=(Q 1=R); 


3. IF (T=NULL) | (T=ADDR(B)) & (S=NULL)) THEN 
P=Q; 


Based Variables 


Although the value of a pointer variable specifies the ab- 
solute address of a data item, the pointer itself provides no 
information about the data item. For example, a pointer 
variable can specify the absolute address of an array A, but 
neither the pointer name nor the pointer value indicates 
the dimensions of A or the characteristics of its elements. 

To associate descriptive information with the address 
value of a pointer vaariable, PL/I provides a special type of 
variable called the based variable, which is declared with 
the attribute: 


BASED (element-pointer-variable) 
The element-pointer variable within the BASED attribute 


cannot be a based variable, nor can it be subscripted. 
Before reference can be made to a based variable, an 


address value must be assigned to the pointer variable 


specified in the associated BASED attribute. Note that 
declaration of a based variable does not assign an address 
value to its associated pointer variable. 


A reference to a based variable applies the attributes of 
the based variable to the storage location specified by the 
associated pointer variable. Consider the declaration: 


DECLARE NAME CHARACTER(15) BASED(P); 


This statement declares the 15-position character string 
called NAME to be a based variable and associates the 
pointer variable P with NAME. For example, let NAME 
appear in the assignment statement: 


NAME = ‘JOHN’; 


This statement assigns the character-string constant 
‘JOHN’ to a 15-position storage area at the location given 
by P. The four characters of the constant are positioned to 
the left in the area and are followed by eleven blank char- 
acters. 


The BASED attribute is a storage-class attribute along 
with AUTOMATIC, CONTROLLED, and STATIC. 
Appearance of BASED in a DECLARE statement, how- 
ever, does not produce an allocation of storage. Only when 
an absolute address is assigned to the pointer variable re- 
lated to the based variable does storage become associated 
with the based variable. Consider, for example, the 
previous declaration of the based variable NAME. Not 
until an absolute address is assigned as the value of pointer 
P does storage become associated with NAME. When this 
association occurs, NAME is said to be “‘based on”’ P. 

The value of the pointer variable in a BASED attribute 
can specify a location of any storage class and data type, 
including an array or a structure. When applied to a struc- 
ture, the BASED attribute must appear at level 1 and, 
consequently, applies to all members of the structure. Care 
must be taken, though, when changing the value of the 
pointer related to a based variable to assure compatibility 
between the attributes of the based variable and the data 
at its newly assigned location. 


Qualifying Based Variables with Pointer Variables 


PL/I allows a based variable to be associated with more 
than one storage area at the same time. This multiple 
association is possible because a based variable by itself 
does not specify a data item, but only a description of 
storage. It is the combination of pointer variable and based 
variable that determines the location and description of a 
data item. 

Since only one pointer variable can appear in a BASED 
attribute, some other facility is required for simul- 
taneously associating two or more pointers with the same 
based variable. The PL/I facility that permits this multiple 
association is called pointer qualification. It is used to 
distinguish among two or more storage areas associated 
with the same based variable, and allows other pointers to 


override the pointer that was specified in the declaration 
of the based variable. 

Pointer qualification is denoted by a composite symbol 
that resembles an arrow. The symbol consists of a minus 
sign followed immediately by a greater-than symbol (—>). 
This composite symbol, however, does not signify an oper- 
ation; its function is similar to that of the period symbol 
used in the qualified name of a structure element. When 
used, the pointer qualification symbol must always appear 
between two references. The reference on the left must be 
either an element-pointer variable or a reference to the 
built-in function ADDR. When it is an element-pointer 
variable, it cannot be subscripted, nor can it be of the 
based-storage class. The reference on the right of the 
pointer qualification symbol must be a based variable. 

A pointer qualification symbol applies the storage de- 
scription of the based variable on its right to the storage 
location specified by the pointer value on its left; the 
pointer originally declared with the based variable is over- 
ridden. As an example, consider the assignment statement: 


A—>B = C—>B; 


Assume that B is a based variable, and A and C are non- 
based, element-pointer variables. The expression C—>B 
refers to a data item that has the attribute declared for B 
and the location specified by C. Similarly, the expression 
A-—>B determines the location and attributes of the area 
to which the data item is assigned. Thus, the pointer qual- 
ification symbols in this example associate the attributes 
declared for the based variable B with the two distinct 
storage areas addressed by pointers A and C. This use of 
the arrow symbol (—>) to associate a based variable with a 
specific pointer variable constitutes pointer qualification. 


Restrictions on Based Variables 


The following restrictions apply to based variables: 

1. The EXTERNAL attribute cannot appear in the 
declaration of a based variable, but a based variable can be 
qualified by an external pointer variable. 

2. Based variables cannot have the INITIAL attribute, 
nor can arrays of based labels be initialized by subscripted 
label prefixes. 

3. Data-directed input and output cannot transmit the 
value of a based variable. 

4. The BASED attribute cannot be specified for the 
parameters of subroutines or functions. 

5. The CHECK ON-condition cannot be applied to a 
based variable. 

6. The VARYING attribute cannot be applied to a 
based variable. 


Contextual Declarations of Pointer Variables 


The appearance of an identifier in one of the following 
contexts serves as a contextual declaration of the identifier 
as a pointer variable: 

1. In a BASED variable 

2. On the left of a pointer qualification symbol (—>) 

3. In the SET option of READ, LOCATE, and ALLO- 
CATE statements (discussed later) 

A contextually declared pointer variable receives the 
AUTOMATIC storage class and INTERNAL scope by 
default. If different attributes are desired, they must ap- 
pear in an explicit declaration along with the POINTER 
attribute. The pointer variable contextually declared with 
a based variable does not receive the null pointer value as a 
result of the based declaration, and only the INITIAL 
CALL form of the INITIAL attribute is allowed in explicit 
declarations of pointer variables. 


Based Storage 


Based variables can be used with ALLOCATE and FREE 
statements for direct control of storage allocation. 
Allocation of storage for a based variable is performed 


with the ALLOCATE statement, which has the basic form: 


ALLOCATE based-variable; 


When executed, this statement allocates storage for the 
based variable and assigns the absolute address of the allo- 
cated storage to the pointer variable specified in the 
BASED attribute of the based variable. The attributes 
associated with the based variable determine the amount 
of storage that is allocated. 


EXAMPLE: 


DECLARE 
TABLE(5) BASED(P) FIXED DECIMAL(3); 


ALLOCATE TABLE; 


These statements declare TABLE to be a based array and 
allocate storage for the array. Each of the five elements in 
the array is a three-digit fixed-point decimal integer. The 
location of the allocated storage for the array is automati- 
cally assigned to pointer P, which appears in the BASED 
attribute of TABLE. 

Reallocation of storage for a based variable does not 
free previously allocated storage for the variable. Instead, 
both the old storage and the new storage are available 
provided the old value of the associated pointer is saved 
before it is automatically replaced by the location of the 
new storage. Several allocations of storage for the same 


based variable may be distinguished by appropriate pointer 
qualification. 


EXAMPLE: 


DECLARE 

T POINTER, 

SWITCH BIT(2) BASED(P); 
ALLOCATE SWITCH; 
T= P; | 
ALLOCATE SWITCH; 
T—>SWITCH = ‘11’B; 
SWITCH = ‘10’B; 


In this example, SWITCH is a based variable that repre- 
sents a two-position bit string. T and P are pointer vari- 
ables. After each allocation of storage for SWITCH, 
pointer P contains the address of the allocated storage. 
Pointer T receives the address of the first allocation before 
the second allocation is executed. The statement T—> 
SWITCH = ‘11’B; assigns the bit-string constant ‘11°B to 
the first storage location allocated for SWITCH. 

As illustrated in the preceding example, each allocation 
of storage for a based variable assigns the address of the 
new allocation to the pointer variable specified in the 
BASED attribute associated with the based variable. When 
two or more allocations of storage are performed concur- 
rently for the same based variable, the addresses of pre- 
vious allocations must be saved in separate pointer 
variables; otherwise, the previous addresses will be lost. 

So far, the address of a previous allocation has been 
saved by the assignment statement. But PL/I also provides 
the SET option in an ALLOCATE statement as an alterna- 
tive method for assigning the address of an allocation to a 
pointer variable. An ALLOCATE statement with a SET 
option has the following form: 


ALLOCATE based-variable SET 
(element-pointer-variable); 


This statement allocates storage for the based variable and 
assigns the address of the allocated storage to the pointer 
variable specified in the SET option. The pointer variable 
must represent a single pointer value; it cannot be the 
name of an array of pointers or a structure of pointers. 

An ALLOCATE statement without a SET option is 
treated as having an implicit SET option that applies to the 
pointer variable in the BASED attribute of the allocated 
variable. An explicit SET option allows the programmer to 
specify a pointer variable different from the one given in 
the BASED attribute of the allocated variable. This other 


pointer receives the address of the allocated storage, and 
the pointer variable in the BASED attribute remains un- 
changed. 


EXAMPLE: 


DECLARE 

P POINTER, 

VALUE BASED(Q) FLOAT; 
ALLOCATE VALUE; 
ALLOCATE VALUE SET(P); 


The first ALLOCATE statement allocates storage for 
VALUE and assigns the location of the storage to pointer 
Q. The second ALLOCATE statement allocates additional 
storage for VALUE and assigns the location of this new 
storage to pointer P. The value of pointer Q and the stor- 
age allocated by the first ALLOCATE statement remain 
unchanged by the second allocation. 

Storage allocated for a based variable is freed for pos- 
sible reuse by the FREE statement, which has the follow- 
ing form: 


FREE based-variable; 


This statement frees the storage currently associated with 
the based variable. The program obtains the address of this 
storage from the current value of the pointer variable de- 
clared in the BASED attribute of the based variable. The 
attributes of the based variable determine the amount of 
storage that is freed. 


EXAMPLE: 


DECLARE 

P POINTER, 

ITEM BASED(Q) CHARACTER(10); 
ALLOCATE ITEM; 
ALLOCATE ITEM SET(P); 


FREE ITEM; 
FREE P—>ITEM; 


In these statements, P and Q are pointer variables, and 
ITEM is a character-string based variable. Two allocations 
of storage occur for ITEM. Pointer Q contains the location 
of the first allocation; pointer P, the second. The first free 
statement frees the storage for ITEM at the location speci- 


fied by Q. The second FREE statement frees the storage 
for ITEM at the location specified by P. 

A based variable can be used to free a particular alloca- 
tion of storage only if that storage has been allocated for a 
based variable with the same attributes, including array 
bounds, string lengths, and arithmetic precisions. An at- 
tempt to free a based variable for which storage has not 
been allocated produces unpredictable results. 


Area Variables 


PL/I provides a type of variable called the area variable, 
which reserves storage for allocations of based variables. 
The area variable permits based allocations to be grouped 
as a unit for convenient input/output transmission or as- 
signment to another area while maintaining the separate 
identity of each allocation. The following discussion de- 
scribes how area variables are used to group based alloca- 
tions. 
An identifier becomes an area variable when it is 

declared with the AREA attribute, which has the form: 


AREA(size-expression ) 


The value of the size expression determines the size of the 
area in bytes. However, the expression is optional; when it 
is not used, an implementation-defined size is assumed by 
the PL/I compiler. 

Although an area variable reserves storage for alloca- 
tions of based variables, it can have any storage class. The 
size of an area with static storage class must appear in the 
AREA attribute as an unsigned fixed-point decimal 
integer constant. The AREA attribute is not restricted to 
element identifiers; it can also be used with array and 
structure identifiers. PL/I also provides for area arguments 
and parameters in subroutines and functions, and the aster- 
isk notation can be used to denote the size of an area 
parameter. The DEFINED attribute permits an area to be 
defined on another area through overlay or corresponding 
defining; both areas, however, must have the same size. 


EXAMPLES: 


DECLARE 
A STATIC AREA (32767), 
B AREA, 
C  AREA(N), 
D AREA(S) CONTROLLED, 
E  AREA(10000) BASED(P), 
F(5) AREA(400), 
1 G, 
2 H AREA(100), 
2 I AREA(200), 
2 J AREA(300), 
K AREA DEFINED B, 
L  AREA(*); 


This DECLARE statement specifies that: 

1. Aisa static area variable that reserves 32767 bytes 
of storage. 

2. B is an automatic area variable that reserves an im- 
plementation—defined amount of storage. 

3. Cis an automatic area variable whose size depends 
on the value of N current at the time the block to which it 
is internal is activated. 

4. Disa controlled area variable whose size depends 
either on the value of S at the time an ALLOCATE state- 
ment allocates storage for D, or on a size specification in 
the ALLOCATE statement, which overrides S. 

5. Eis a based area variable that reserves 10,000 bytes 
of storage for each allocation. 

6. F is an array that contains five area elements, each of 
which reserves 400 bytes of automatic storage. 

7. Gis an area structure that contains the three areas H, 
I, and J. H reserves 100 bytes of automatic storage, I re- 
serves 200 bytes, and J reserves 300 bytes. 

8. K is an area defined on area B. 

9. Lis an area parameter that assumes the same size as 
its associated area argument in a subroutine or function 
invocation. 


Allocating and Freeing Based Storage in an Area 


The ALLOCATE statement uses the IN option for based 
allocations within a specified area: 


ALLOCATE based-variable 
SET(pointer-variable) IN(area-variable); 


This statement allocates storage for the based variable 
within the specified area and assigns the location of the 
allocated storage to the pointer variable. The IN option, 
however, is not required; when it is not used, the based 
variable is allocated in a storage area provided by the 
operating system. 

The FREE statement, as applied to a based allocation in 
a specified area, has the form: 


FREE based-variable 
IN(area-variable); 


The IN option must appear in a FREE statement if the 
based allocation was made within an explicitly specified 
area; Otherwise, the option is omitted. 


EXAMPLE: 
DECLARE 
STORE AREA(500) BASED(P), 
VALUE BASED(Q) FIXED DECIMAL(5,2), 
R POINTER; 


ALLOCATE STORE; 
/* P ADDRESSES AREA STORE. */ 


ALLOCATE VALUE IN(STORE); 
/* Q ADDRESSES ALLOCATION OF VALUE 
IN STORE. */ 


ALLOCATE VALUE IN(P—>STORE) SET(R); 
/* R ADDRESSES SECOND ALLOCATION 
OF VALUE INSTORE. */ 


FREE VALUE IN(STORE); 
/* FREES ALLOCATION OF VALUE 
ADDRESSED BYQ. +*/ 


FREE R—>VALUE IN(STORE); 
/* FREES ALLOCATION OF VALUE 
ADDRESSED BY R._ */ 


The first ALLOCATE statement allocates 500 bytes of 
storage for area STORE and assigns the location of the 
allocated storage to pointer P. 

The second ALLOCATE statement causes storage for 
based variable VALUE to be allocated within P->STORE 
and assigns the location of the allocated storage to pointer 
Q. | 

The third ALLOCATE statement generates another 
allocation of VALUE (different from Q—>VALUE) within 
area P—~>STORE and sets pointer R equal to the location 
of the allocated storage. 

The FREE statements employ the IN option because 
allocations of VALUE were explicitly made in STORE. 
Although the allocations of VALUE become free, the 
storage for area STORE remains allocated. 


Emptying an Area 


When an area is allocated, it automatically receives the 
empty state; that is, it contains no allocations of based 
variables. An area that is not empty can be made empty by 
assigning an empty area to it or by assigning the value of 
the built-in function EMPTY: 


AREA1 = EMPTY; 
AREA2 = AREAI; 


The AREA ON-condition 


An attempt to allocate based storage within an area that 
contains insufficient free storage for the allocation pro- 
duces an AREA ON-condition. If no ON-unit appears in an 
ON statement for the AREA condition, the operating 
system issues a comment and raises the ERROR condition. 

When an ON-unit is specified and normal return occurs 
from the ON-unit, the ALLOCATE statement that raised 
the AREA condition is executed again. If the ON-unit has 
changed the value of a pointer qualifying (explicitly or 
implicitly) the reference to the inadequate area so that the 
pointer value specifies another area, the allocation is reat- 
tempted within the new area. Failure of the ON-unit to 
provide a larger area may place the program in an error 
loop. 


Linking Allocations of Based Storage in an Area 


Techniques for processing lists depend upon the ability to 
link collections of noncontiguous data items in any desired 
order by attached address elements. The PL/I structure 
Organization provides a convenient way of attaching an 
address element to a data item. As an example, consider 
the declaration: 


DECLARE 
1 COMPONENT BASED(P), 
2 DATA CHARACTER(80), 
2 LINK POINTER; 


COMPONENT is a based structure that contains two ele- 
ments: DATA, which is a character string of 80 positions, 
and LINK, which is a pointer variable. Placing LINK and 
DATA in the same structure effectively attaches LINK to 
DATA. The diagram in Figure 1.1 illustrates this attach- 
ment. Rectangles represent storage for DATA and LINK, 
and the protruding arrow indicates that LINK is a pointer 
variable whose value points to another allocation of stor- 
age. 


DATA LINK 


Figure 1.1. A data element with an attached pointer 


Based structure COMPONENT may be used to allocate 
and link storage throughout an area, as indicated in Figure 
1.2. The following statements show how such organization 
of storage may be performed. 


DECLARE 
AREA1 AREA(1000), 
(AVAIL, TEMP, P) POINTER, 
1 COMPONENT BASED(P), 
2 DATA CHARACTER(80), 
2 LINK POINTER; 

/* WHEN ALL STORAGE HAS BEEN ALLOCATED IN 
AREAI, SET LINK POINTER OF LAST COM- 
PONENT TO NULL AND GO TO LABEL NEXT. */ 

ON AREA 

BEGIN; P—>LINK=NULL; GO TO NEXT; END; 

/* ALLOCATE FIRST COMPONENT IN AREA1I AND 
ASSIGN THE COMPONENT ADDRESS TO 
POINTER AVAIL. */ 

ALLOCATE COMPONENT IN(AREA1) SET(P); AVAIL 

=P; 


/* CONTINUE ALLOCATING COMPONENTS IN 
AREA1 UNTIL ALL STORAGE HAS BEEN ALLO- 
CATED. LINK EACH COMPONENT TO THE PRE- 
VIOUSLY ALLOCATED COMPONENT. */ 
L: TEMP = P; 
ALLOCATE COMPONENT IN (AREA1) SET(P); 
TEMP—>LINK = P; 
GO TO L; 

NEXT: 


Pointer AVAIL contains the address of the first allocation 
of COMPONENT in AREA1, and the LINK pointer of 
each allocation contains the address of the next allocation. 
A null address is assigned to the LINK pointer of the last 
allocation. 

The organization shown in Figure 1.2 establishes 
AREA1 as a pool of available storage components from 
which free storage may be obtained when needed. Pointer 
AVAIL provides access to the first storage component, and 
successive components are reached by proceeding through 
the LINK pointers of the components. Chaining storage 
components in this way forms a special type of data organ- 
ization called a list, which may be referred to by the name 
of the head pointer AVAIL. 

Figure 1.3 illustrates how the first two components 
linked to AVAIL may be removed from AVAIL and linked 
to another head pointer to form a second list called LIST1. 
Similarly, when the components of LIST1 are no longer 
needed, they can be relinked to AVAIL, where they be- 
come available to other lists. 


AREAT 





Figure 1.2. Allocations of based storage linked by pointer variables 


AREAIl 


List) | ~ DATA 


AVAIL “DATA 


LINK DATA LINK 


|} NULL 


DATA | LINK 


LINK 


~ DATA | LINK DATA LINK 


DATA LINK DATA LINK 


NULL 


Figure 1.3. Linking available storage components to another list 


This type of storage manipulation permits the storage 
requirements of a list to vary during the course of program 
execution. A list need reserve only the storage it is actually 
using at any given moment; storage need not lie dormant 
within each list in anticipation of maximum storage re- 
quirements, as it often does in conventional array and 
structure organizations. As a result, the programmer is 
freed from having to know exactly how much storage each 
list will require. 

Linking storage by means of attached address elements 
can improve the execution time of a program by reducing 
the amount of data that must be moved. For example, if 
the components of a list are to be sorted on their data 
values, it is not necessary to change the physical positions 
of the data values in storage; their logical positions within 
the list can be changed by manipulating the attached ad- 
dress elements. Logically successive components need not 
occupy physically successive storage locations. Scattered 
components can be linked in any desired order. 


Head 


POINTER 


Figure 1.4. Data list 






DATA LISTS 


The type of list organization illustrated in Figures 1.2 and 
1.3 is called a data list because it consists of linked data 
items. The lists in those illustrations possess a linear order- 
ing: each component except the first has one predecessor, 
and each component except the last has one successor. As 
Figure 1.4 shows, this type of list consists of a head and a 
body. The head is a pointer variable that identifies the list 
and contains the address of the first component in the list. 
The body is a sequence of list components, each of which 
contains a data item and a pointer variable. Except for the 
last pointer, which has a null address, the pointer in a 
component contains the address of the next component in 
the list. 

This type of list organization always requires a head and 
permits the body of a list to contain an arbitrary number 
of components, limited only by available storage. It is 
even possible for the body of a list to contain no com- 
ponents; in this case, the list is said to be null (see Figure 
1.5). 

Figures 1.4 and 1.5 do not show the area within which 
storage has been allocated for list components. These illus- 
trations emphasize the main parts of a list and deempha- 
size the environmental aspects of list organization. They 
also stress the close resemblance between this type of list 
and a character string or a one-dimensional array, the 
major difference being that successive components of a list 
need not occupy contiguous storage locations. 

Examples of subroutines used to allocate based 
variables throughout an area are provided in this manual. 





DATA POINTER 


Head 


POINTER 


N 





ULL | 


Figure 1.5. Null list 


Chapter 2: Simple Data Lists 


This chapter develops methods for organizing and manipu- 
lating simple data lists and shows how these methods may 
be used in list-processing applications. 


ORGANIZING SIMPLE DATA LISTS 


To avoid unnecessary complexity, this chapter uses a 

simple list organization in which each list component con- 
tains a single alphameric character for its data element. As 
an example, consider this illustration of a simple data list: 


Head 


POINTER 


DATA POINTER 


This list contains three characters: A, >, and O; each isa 
separate component of the list. The identifier L1, attached 
to the head of the list by a colon, specifies the name of the 
head pointer and, therefore, serves as the name of the data 
list. 

Elimination of descriptive words from the elements of 
the list produces a more compact illustration: 


u: ChaLDbELDbEN 


Note that a diagonal rather than the keyword NULL in- 
dicates a null pointer. The following representation, there- 
fore, specifies that L2 is a null list: 


LZ: 


Also observe that a list of one or more blank characters is 


not a null list, since a blank is an encodable machine char- | 


acter even though it does not have a printable graphic. The 
following list, L3, contains two blank characters: 
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Body 


DATA POINTER DATA POINTER 





Restricting the data element of each list component 
to a single character simplifies the task of developing and 
illustrating list-processing techniques. It also permits 
analogies to be developed between simple data lists and 
character strings. 

The above illustrations of data lists, however, are com- 
pletely arbitrary and do not form a necessary feature of 
PL/I. 

Chapter 3 discusses data lists with more complex organ- 
izations that require more elaborate illustrations. 


PROCESSING SIMPLE DATA LISTS 


All data lists, despite the variety of their possible applica- 
tions, undergo common basic operations, such as inserting, 
retrieving, and deleting list items. Because most operations 
performed on lists require several steps, which may be 
repeated many times during the course of program execu- 
tion, it is often more convenient and efficient to provide 
these operations in subroutine or function form rather 
than as independent sets of PL/I statements that must be 
duplicated throughout a program. The following discus- 
sions show how a collection of subroutines and functions 
can be designed to simplify many list-processing opera- 
tions. The routines cover five general categories: 

1. Creating a list of available storage components 

2. Manipulating the elements of list components 

3. Manipulating list components (not just their ele- 
ments) 

4. Manipulating sublists and lists 

5. Manipulating lists recursively 


A hierarchical approach is taken in the development of 
routines for each of these categories. Procedures con- 
cerned with the primitive aspects of storage allocation are 
programmed first and are used in turn to create higher 
level procedures. This approach limits the number of pro- 
cedures that deal with environmental factors and permits 
the complete collection of subroutines and functions to 
possess an application-oriented emphasis. 

The sequential organization of the routines is main- 
tained so that each routine uses only those list-processing 
procedures that have been developed earlier. No attempt is 
made at complete programming efficiency. Wherever pos- 
sible, programming methods have been chosen to simplify 
the presentation for the reader rather than to produce 
efficient code. 


Creating a List of Available Storage Components 


The amount of storage needed by a data list can vary 
during the course of program execution. As new data items 
are inserted into the list, additional storage is required, and 
when data items are deleted from the list, the associated 
storage becomes free. 

The list-processing techniques developed in this chapter 
assume that any storage not needed by a data list is re- 
served in a special list of available storage components. 
This special list serves as a storage pool, which initially 
contains all the storage used to form the components of 
other lists. 

As a data list grows, additional storage for the list is 
obtained from the list of available storage components. 
Similarly, when list components become free, their storage 
is returned to the list of available storage components. As a 
result, the same storage can be used by many different lists 
during the execution of a program. Sharing storage in this 
way reduces the amount of storage that might lie dormant 
within individual data lists in anticipation of maximum 
storage requirements for each list. 

The creation of a list of available storage components is 
performed in this chapter with the AREA OPEN subrou- 
tine, which is discussed next. 


AREA_ OPEN Subroutine 


Figures 2.1A, 2.1B, and 2.1C present the AREA OPEN 
subroutine, which requires two arguments: 

1. An area variable throughout which list components 
are allocated 

2. A pointer variable that serves as the head of the list 
of available storage components 


AREA_OPEN Subroutine 


Purpose 
To create a list of available storage components 


Reference 
AREA_OPEN(AREA, LIST) 


Entry-Name Declaration 
DECLARE AREA_OPEN ENTRY(AREA\("*), 
POINTER); 


Meaning of Arguments 
AREA _ --the area variable that is to contain the list 
of available storage components 
--the pointer variable that serves as the head 
of the list of available storage components 


LIST 


Remarks 
Storage must have been allocated for the AREA 
argument before AREA_OPEN is invoked. The 
LIST argument is assumed to be null upon entry 
to AREA_OPEN. 


Other Programmer-Defined Procedures Required 
None 


Method 
Storage for list components is allocated with the 
following based structure: 


1 COMPONENT BASED(P), 
2 DATA CHARACTER(1), 
2 POINTER POINTER, 


Components are allocated throughout AREA until the 
AREA ON-condition occurs. 


The LIST argument contains the address of the first 
component. The POINTER element of each component 
contains the address of the next component. The 
POINTER element of the last component is null. 





Figure 2.1A. Description of the AREA OPEN subroutine for 
creating a list of available storage components 


1] 


AREA_OPEN: 

PROCEDURE 
(AREA,LIST)$ 

DECLARE 

AREA AREA(*), 
(LIST, Py T) POINTER, 
1 COMPONENT BASED(P), 
2 DATA CHARACTER(1), 
2 POINTER POINTERS 
/* WHEN ALL STORAGE HAS BEEN 
ALLOCATED IN AREA, SET POINTER OF 
LAST COMPONENT, IF ANY» TO NULL AND 
LEAVE SUBROUTINE. */ 


ON AREA 
BEGINS; 
IF 
Pa=NULL 
THEN 
P—~>POINTER = NULLS3 
GO TO 
END_AREA_OPEN; 
END; 


/* ALLOCATE FIRST COMPONENT IN 
AREA, AND ASSIGN COMPONENT ADDRESS 
TO THE POINTER PARAMETER CALLED 
LIST. */ 
P = NULL; 
ALLOCATE COMPONENT INCAREA) 
SET(P)5 
LIST = P; 
/* CONTINUE ALLOCATING COMPONENTS IN 
AREA UNTIL ALL STORAGE HAS BEEN 
ALLOCATED. LINK EACH COMPONENT 
TO THE PREVIOUSLY ALLOCATED 
COMPONENT. */ 

Ls; T = P; 
ALLOCATE COMPONENT IN(AREA) SET(P)3 
T->POINTER = P3 

GO TO 

L; 

END_AREA_OPEN: 

END 
AREA_OPENS 


Figure 2.1B. Creating a list of available storage components for 
data lists | 


The area argument passed to AREA OPEN can be of 
any storage class and is not restricted to a particular size, 
but storage for the area must have been allocated before 
the subroutine is invoked. Although only one area is spec- 
ified in an invocation of AREA OPEN, several invocations 
of the subroutine can allow the list of available storage 
components to occupy more than one area. 

The AREA_ OPEN subroutine must be invoked at least 
once before another list-processing procedure is used; 
otherwise, no storage will be available for list formation. 
The sample procedures in this chapter use the identifier 
LIST as the head pointer of the data list being acted upon. 
The external identifier AVAIL is used as the head pointer 
of a list of storage components that can be inserted into 
the list named LIST. A list component in LIST that be- 
comes superfluous can be deleted from LIST and inserted 
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into AVAIL. As later procedures demonstrate, declaring 

AVAIL to be an external identifier avoids having to pass 

the name of the list of available storage components as an 

argument each time it is used by a subroutine or function. 
The AREA OPEN subroutine can be invoked to create 

a list of components named LIST and again to create a 

list of components named AVAIL: 


CALL AREA OPEN (AREA1,LIST); 
CALL AREA OPEN (AREA2,AVAIL); 


Note that the allocation of a based variable into an area 
is optional; list components in scattered locations can be 
linked by their pointer elements. However, an area con- 
taining list components linked by offset variables can be 
moved about in main storage or transmitted to and from 
external storage. An offset variable is a storage address that 
is relative to the address of the beginning of an area. (See 
Introduction to the List Processing Facilities of PL/T, 
GF20-0015, for discussion and illustration of the use of 
offset variables in forming and transmitting relocatable 
data lists.) 


Manipulating the Elements of List Components 


All list-processing operations involve at least one of these 
items: 

1. Address of a list component 

2. Data element of a list component 

3. Pointer element of a list component 


The following discussions develop subroutines and func- 
tions that: 

1. Obtain the address of a list component 

2. Assign values to the data and pointer elements of a 
list component 

3. Obtain the values of the data and pointer elements 
of a list component 


These procedures eliminate the syntactic details asso- 
ciated with PL/I pointer qualification and allow the pro- 
grammer to view and process data lists in an application- 
oriented manner. 


Obtaining the Address of a List Component 


Because a list component is formed by allocating a based 
variable, the address of the component must be obtained 
before it can be processed. The following discussions de- 
velop two function procedures that obtain the address of a 
specified list component: 

1. ADDRESS_N, which obtains the address of the nth 
component in a data list 

2. ADDRESS NEXT, which obtains the address of the 
list component that follows a given component 


el 





Subroutine 
Reference 


AREA_OPEN (STORAGE_ AREA, AVAIL) 


AVAIL: za 


Figure 2.1C. An example of a reference to the AREA OPEN subroutine 


Result 


STORAGE AREA 


ae. oe ee ee 
Pt PLE LL RIN 





ADDRESS _N Function Figures 2.2A and 2.2B present the 
ADDRESS_N function procedure. This function requires 
two arguments: | | | 

1. A pointer variable that forms the head of the data 
list in which the specified component appears 

2. An integer that specifies the sequential list position 
(first, second, third, etc.) of the component whose address 
is desired | 


The function returns the address of the specified com- 
ponent. 


ADDRESS_N Function 


Purpose 
To obtain the address of the nth component of a 
data list 


Reference 
ADDRESS_N(LIST, N) 


Entry-Name Declaration 
DECLARE ADDRESS_N ENTRY(POINTER, 
FIXED DECIMAL(5)) 
RETURNS(POINTER); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be examined 
N --a fixed-point decimal integer value that 
specifies the component whose address is to 
be obtained; N has a maximum size of five 
digits | 


Remarks 
A null pointer value is returned when LIST is null, 
N is less than one, or N is greater than the number 
of components in LIST. 


Other Programmer-Defined Procedures Required 
None 


Method | 
The function proceeds through LIST until the 
(n-1)th component is reached. The pointer element 
of this component contains the address of the nth 
component. 


Figure 2.2A. Description of the ADDRESS _N function for 
obtaining the address of the nth component of 
_a data list 
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ADDRESS_N:? 
PROCEDURE(LIST, N) 
RETURNS (POINTER); 
DECLARE 
(LIST, ADORESS) POINTER, 
(NyI) FIXEO OECIMAL(5), 
1 COMPONENT BASED(ADORESS), 
2 DATA CHARACTER(1), 
2 POINTER POINTER? 
IF 
(LIST = NULLIT (NCL) 
THEN 
RETURN (NULL)3 
ADORESS = LIST; 


DO 
I = 1 BY 13 
IF 
(ADDRESS->POINTER = NULL) & 
(I-2N) 
THEN 
RETURN (NULL) 3 
IF 
I = WN 
THEN 
RETURN( ADDRESS); 
ADDRESS = ADORESS—>POINTER; 
END; 
END 


ADDRESS_N3$ 


Figure 2.2B. Obtaining the address of the nth component of a data 
list 


ADDRESS _NEXT Function When list components are 
processed in sequence, it is inefficient to use the AD- 
DRESS _N function to obtain successive list components, 
because the function always searches for a component 
from the beginning of the list. Figures 2.3A and 2.3B 
present the ADDRESS NEXT function, which causes the 
address of one list component to obtain the address of the 
next component in sequence. ADDRESS NEXT obtains 
the address of the next component directly from the 


pointer element of the component that is specified by the 


address argument in an invocation of the function. 


Assigning Values to the Elements of List Components 


When data items are inserted into or deleted from a data 
list, the data and pointer elements of list components must 
be changed. The following discussions develop two subrou- 
tines that perform such changes: 

1. SET_DATA, which assigns a value to the data ele- 
ment of a list component 

2. SET_POINTER, which assigns a value to the pointer 
element of a list component 


SET_DATA Subroutine Figures 2.4A and 2.4B present 
the SET_DATA subroutine, which requires two argu- 
ments: 

1. Address of a data list component 

2. Character value to be assigned to the data element of 
the list component 


ADDRESS_NEXT Function 


Purpose 
To obtain the address of the next component ina 
data list 


Reference 
ADDRESS_NEXT(ADDRESS) 


Entry-Name Declaration 
DECLARE ADDRESS_ NEXT ENTRY(POINTER) 
RETURNS(POINTER); 


Meaning of Argument 
ADDRESS --a pointer value that specifies the 
address of a data list component 


Remarks 
The function assumes that ADDRESS represents a 
valid address of a data list component. If ADDRESS 
is null, a null pointer value is returned. 


Other Programmer-Defined Procedures Required 
None 


Method 
The function returns the address contained in the 
pointer element of the component specified by 
ADDRESS. 


Figure 2.3A. Description of the ADDRESS NEXT function 
for obtaining the address of the next component 
in a data list 


ADDRESS_NEXT: 
PROCEDURE (ADDRESS) 
RETURNS (POINTER); 
DECLARE 
ADDRESS POINTER, 
1 COMPONENT BASED( ADDRESS), 
2 DATA CHARACTER(1), 
2 POINTER POINTERS 
IF 
ADDRESS = NULL 
THEN 
RETURN (NULL) $ 
RETURN(ADORESS—>POINTER) 


ADDRESS_NEXTS$ 


Figure 2.3B. Obtaining the address of the next component ina 
data list 





SET DATA Subroutine 


Purpose 
To assign a value to the data element of a data list 
component 


Reference 
SET DATA(ADDRESS, D) 


Entry-Name Declaration 
DECLARE SET_DATA ENTRY(POINTER, 
CHARACTER(1)); 


Meaning of Arguments 
ADDRESS --a pointer that specifies the address of a 
data list component 
D --the value to be assigned to the data 
element of the list component 


Remarks 
The subroutine assumes that ADDRESS represents 
a valid address of a data list component. If ADDRESS 
is null, no assignment is made. 


Other Programmer-Defined Procedures Required 
None : 


Method 
The value of D is converted, if necessary, to a 
character string. The leftmost character of the string 
is assigned to the data element of the specified 
element. 


Figure 2.4A. Description of the SET DATA subroutine for 
assigning a value to the data element ofa 
component in a data list 


SET_DATA: 
PROCEDURE (ADDRESS,0)3 
DECLARE 
ADDRESS POINTER, 
D CHARACTER(1), 
1 COMPONENT BASED( ADDRESS), 
2 DATA CHARACTER(1), 
2 POINTER POINTERS 
IF 
ADORESS = NULL 
THEN 
RETURNS 
ADDRESS->DATA = D; 
END 
SET_DATAS 


Figure 2.4B. Assigning a value to the data element of a component 
in a data list 
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Because the subroutine uses the address of a list com- 
ponent, the character value is assigned directly to the data 
element, and no search is made for the appropriate com- 
ponent from the beginning of the associated list. Later 


discussions present other methods for inserting data items 


into lists. 


SET POINTER Subroutine Figures 2.5A and 2.5B present 
the SET_POINTER subroutine. This procedure is similar 
to SET_DATA (Figures 2.4A and 2.4B) except that it 
assigns an address value to the pointer element of a speci- 
fied list component. 


SET_POINTER Subroutine 


Purpose | 
To assign a value to the pointer element of a data 
list component | 


Reference 
SET_POINTER(ADDRESS, P) 


Entry-Name Declaration 
DECLARE SET_POINTER ENTRY(POINTER, 
POINTER); 


Meaning of Arguments 
ADDRESS --a pointer value that specifies the 
address of a data list component 
P --the value to be assigned to the pointer 
element of the list component 


Remarks 
The subroutine assumes that ADDRESS represents a 
valid address of a data list component. If ADDRESS 
is null, no assignment is made. 


Other Programmer-Defined Procedures Required 
None 


Method 
The pointer value represented by P is sesianed to the 
pointer element of the specified component. 





Figure 2.5A. Description of the SET POINTER subroutine for 
assigning a value to the pointer element of a 
component in a data list 
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SET_POINTER? 

PROCEDURE (ADDRESS »P)3 
DECLARE 

P POINTER, 

ADORESS POINTER, 

1 COMPONENT BASED(ADORESS)+ 

2 DATA CHARACTER(1), 

2 POINTER POINTER? 


IF 
AOORESS = NULL 
THEN 
RETURN; 
ADORESS->POINTER = P$ 
END 


SET_POINTERS 


Figure 2.5B. Assigning a value to the pointer element of a 
component in a data list 


Obtaining the Values of Elements in List Components 


Many list-processing operations examine the values of the 
data and pointer elements in list components. The follow- 
ing discussions develop two function procedures that ob- 
tain these values: 

1. GET_ DATA, which obtains the value of the data 
element in a data list component 

2. GET_POINTER, which obtains the value of the 
pointer element in a data list component 


GET_DATA Function Figures 2.6A and 2.6B present the 


GET_DATA function, which uses the address of a list 
component as its argument. The function returns the char- 
acter value of the data element in the specified list com- 
ponent. 


GET_POINTER Function Figures 2.7A and 2.7B present 
the GET POINTER function. This procedure is similar to 
GET_DATA (Figures 2.6A and 2.6B) except that it ob- 


tains the value of the pointer element in a specified list 


component. 

Note that GET POINTER obtains the same value as 
ADDRESS_NEXT (Figures 2.3A and 2.3B). The reason 
for having two different names for the same function is to 
provide an application-oriented emphasis in later pro- 
cedures. When the pointer value in a list component is 
treated as the address of the next component, it is conven- 
ient to think in terms of the identifier ADDRESS NEXT. 
On other occasions, when the pointer value is used for 
chaining purposes and the emphasis is not on the next list 
component, the identifier GET POINTER conveys a more 
accurate description of the intended effect. In either case, 
the two functions are aietenaneeeele, since they produce 
the same result. 


GET DATA Function 


Purpose 
To obtain the value of the data element in a data 
list component 


Reference 
GET DATA(ADDRESS) 


Entry-Name Declaration 
DECLARE GET_DATA ENTRY(POINTER) 
RETURNS(CHARACTER(1)); 


Meaning of Argument 
ADDRESS --a pointer value that specifies the address 
of a data list component 


Remarks 
The function assumes that ADDRESS represents a 
valid address of a data list component. If ADDRESS 
is null, a blank character is returned. 


Other Programmer-Defined Procedures Required 
None 


Method 
The function returns the value of the data element in 
the specified component. 


The value is a single alphameric character. 





Figure 2.6A. Description of the GET DATA function for 
obtaining the value of the data element of a 
component in a data list 


GET_DATAS 
PROCFDURE (ADORESS) 
RETURNS (CHARACTER(1))3 
DECLARE 
ADDRFSS POINTER, 
1 COMPONENT BASEOC ADDRESS)» 
2 DATA CHARACTER] Dy 
2 POINTER POINTERS 
IF 
ADDRESS = NULL 
THEN 
RETURN(* *)¢ 
RETURN( ADODRESS->DATA)$ 
END 
GET_DATA$ 


Figure 2.6B. Obtaining the value of the data element ina 
component of a data list 


GET_POINTER Function 


Purpose 
To obtain the value of the pointer element in a data 
list component 


Reference 
GET POINTER(ADDRESS) 


Entry-Name Declaration 
DECLARE GET POINTER ENTRY(POINTER) 
RETURNS(POINTER); 


Meaning of Argument 
ADDRESS --a pointer value that specifies the address 
of a data list component 


Remarks 
The function assumes that ADDRESS represents a 
valid address of a data list component. If ADDRESS 
is null, a null pointer value is returned. 


Other Programmer-Defined Procedures Required 
None 


Method 
The function returns the value of the pointer element 
in the specified component. 





Figure 2.7A. Description of the GET POINTER function for 
obtaining the value of the pointer element of a 
component in a data list 


GET_POINTER: 
PROCEDURE (ADDRESS) 
RETURNS (POINTER)D$ 
DECLARE 
ADDRESS POINTER, 
1 COMPONENT BASED( ADDRESS), 
2 DATA CHARACTER(1), 
2 POINTER POINTERS 
IF 
ADDRESS = NULL 
THEN 
RETURN (NULL) 35 
RETURN ( ADORESS—>POINTER)$ 
END | 
GET_POINTER; 


Figure 2.7B. Obtaining the value of the pointer element in a 
component of a data list 
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Examples 


Figure 2.8 contains examples of references to the 
ADDRESS_N, ADDRESS_ NEXT, SET_DATA, and 
GET_DATA procedures. GET_POINTER and 

SET POINTER are not illustrated, because 

GET_ POINTER is equivalent to ADDRESS _ NEXT, and 
later discussions present a more appropriate opportunity 
for demonstrating the effect of SET POINTER. 





Subroutine and Function 
Reference 


SET_DATA(ADDRESS_N(L1,4),’A’) 


SET_DATA(ADDRESS_NEXT(ADDRESS_N(L2,2)),’X’) 


SET_DATA(ADDRESS_N(L3,2),GET_DATA(ADDRESS_N(L3,3))) 


Data List 
(before reference) 


La: || is] feoicN 
us: |_ Font] Pez] pes] PIN 


Data List 
Lt KLHELHEN 
L2; | beLal +e] POXN 





Se cE NN 





Figure 2.8. Examples of references to the ADDRESS _N, ADDRESS NEXT, SET_DATA, and GET_ DATA procedures 


Note how the functions ADDRESS_N, 
ADDRESS_ NEXT, and GET_DATA appear as arguments 
of other procedures. Nesting function references in this 
manner is called function composition and is permitted to 
an arbitrary depth. Function composition forms an es- 
sential feature of the list-processing techniques developed 
in this manual; it produces compact references and reduces 
the need for intermediate variables in which to save func- 
tion values. 


Manipulating List Components 


The procedures in the previous section deal with list com- 
ponents individually; they manipulate the parts (elements) 
of list components but do not associate components with 
one another. The following discussions develop procedures 
for manipulating collections of list components. They also 
suppress much of the environmental detail underlying the 
structure of list organization and show how simple data 
lists may be viewed as sequences of data items rather than 
as sequences of storage components. Asa result, the ap- 
plication-oriented aspects of list organization receive 
greater emphasis. 
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The operations performed by the procedures in this 
section fall into eight general categories: 

1. Obtaining the size of a data list 

2. Inserting data items into data lists 

3. Getting the values of data items in data lists 

4. Deleting data items from data lists 

5. Removing data items from data lists (and at the same 
time getting the values of the items) 

6. Replacing data items in data lists 

7. Searching for data items in data lists 

8. Interchanging data items in data lists 


Most of the procedures in these categories are constructed 
from previously developed procedures. This method of 
construction shows how the procedures may be organized 
into an integrated collection. 


Obtaining the Size of a Data List 


A simple but common operation performed on data lists is 
counting the number of data items in a list. The following 
discussions develop two function procedures for obtaining 
the size of a list: 

1. SIZE, which uses the ADDRESS NEXT subroutine 
(presented earlier in Figure 2.3B) 

2. SIZE1, which does not use other list-processing 
procedures 


The reason for presenting two versions of the same 
function is to show how a procedure may be treated either 
as a primitive routine that does not use other procedures or 
as a higher level routine that is constructed from one or 
more previously developed procedures. 


SIZE Function Figures 2.9A, 2.9B, and 2.9C present the 
SIZE function. This function uses a pointer argument that 
forms the head of the list whose size is desired. The func- 
tion returns a count of the data items in the specified list. 


SIZE Function 


Purpose 
To obtain the number of data items in a data list © 


Reference 
SIZE(LIST) 


Entry-Name Declaration 
DECLARE SIZE ENTRY(POINTER) 
RETURNS(FIXED DECIMAL (5));: 


Meaning of Argument 
LIST --the pointer variable that is the head of the 
list to be examined 


Remarks 
The maximum size is 99999. If LIST is null, a zero 
size is returned. 


Other Programmer-Defined Procedures Required 
ADDRESS NEXT 


Method 
The function proceeds through LIST, counting 
the number of list components until! a null pointer 
element is encountered. 





Figure 2.9A. Description of the SIZE function for obtaining the 
number of data items in a data list 


Data List 


L4: 


were 





SIZE: 
PROCEDURE (LIST) 
RETURNS (FIXED DECIMAL(5))3 
DECLARE 
(LIST,ADORESS) POINTER, 
N FIXED DECIMAL(5)$ 
ADDRESS = LIST$ 
DO 
N = O BY 13 
IF 
ADORESS = NULL 
THEN 
RETURN(N)$ 
ELSE 
ADORESS = ADORESS_NEXT(C ADDRESS) 3 


SIZE$ 


Figure 2.9B. Obtaining the size of a data list 


The ADDRESS_NEXT procedure is used to proceed 
through a list until a null pointer element is detected. 


SIZE1 Function Figures 2.9D and 2.9E present the SIZE1 
function, which produces the same result as the SIZE 
function (Figures 2.9A through 2.9C). The main difference 
between the two functions is that SIZE1 uses no other 
list-processing procedures; it is constructed as a primitive 
routine that uses pointer qualification of a based variable 
rather than a function reference to proceed through a 
specified list. 


Inserting Data Items into Data Lists 


So far, list-processing procedures have assumed the exist- 
ence of data lists and have not shown how list components 
are attached to specified lists. When a data item is inserted 
into a list, a storage component must be obtained from the 
list of available storage components (AVAIL) and linked 
to the list that is to contain the inserted item. Without this 
storage component, no storage would be available for the 


new item. 
Function Function 
Reference Value 


SIZE(L1) 
SIZE (L2) 
SIZE(L3) 


SIZE(L4) 





Figure 2.9C. Examples of references to the SIZE function 
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SIZE1 Function 


Purpose 
To obtain the number of data items in a data list. 


Reference 
SIZE1(LIST) 


Entry-Name Declaration 
DECLARE SIZE1 ENTRY(POINTER) 
RETURNS(FIXED DECIMAL (5)); 


Meaning of Argument 
LIST --the pointer variable that is the head of the list 
to be examined 


Remarks 


The maximum size is 99999. If LIST is null, a zero 
size is returned. 


Other Programmer-Defined Procedures Required 
None 


Method 
The function proceeds through LIST, counting the 
number of list components until a null pointer 
element is encountered. | 





Figure 2.9D. Description of the alternate function SIZE1 for 
obtaining the number of data items in a data list 


SIZE1:3 
PROCEDURE (LIST) 
RETURNS (FIXED DECIMAL(5))3 
DECLARE 
| LIST POINTER, 
ADDRESS POINTER, 
N FIXEO DECIMAL(5), 
1 COMPONENT BASEDOC ADDRESS), 
2 DATA CHARACTER(1), 
2 POINTER POINTER? | 
ADDRESS = LIST? 
00 | 
N = O BY 13 
IF | 
ADORESS = NULL 
THEN | 
RETURN(N)D3 
ELSE 
ADDRESS = ADDRESS->POINTERS 
ENDS; 
END | 
STZE13 


Figure 2.9E. An alternative function for obtaining the size of a 
data list | 
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The following discussions develop four subroutine pro- 
cedures that insert data items into specified list positions: 

1. INSERT_ND, which inserts a data item into the nth 
position of a data list — 

2. INSERT_ FD, which inserts a data item into the first 
position of a data list 

3. INSERT _LD, which inserts a data item into the last 
position of a data list 

4. INSERT _ND1, which produces the same results a as 
INSERT_ND but does not use other list-processing pro- 
cedures 


INSERT _ND Subroutine Figures 2.10A and 2.10B pres- 
ent the INSERT ND subroutine procedure, and examples 
of the procedure appear in Figure 2.10G. INSERT _ND 
uses three arguments: a data list, a position within the list, 
and a data item to be inserted at that position in the list. 
Insertion of a data item into a list increases the size of 
the list by one and at the same time decreases the size of 
the list of available storage components (AVAIL) by one. 
The size of AVAIL can also be zero when INSERT_ND is 
invoked; in this case, no data is inserted into the specified 
list, but a message is printed, and control is returned to the 
point of invocation. In a more elaborate system of pro- 
cedures, attempted use of AVAIL when it is null can trans- 
fer control to an error procedure where special action can 
be taken, such as allocating additional storage for AVAIL. 


INSERT _FD Subroutine Figures 2.10C and 2.10D pres- 


ent the INSERT_FD subroutine procedure, which inserts 


a data item into the first position of a data list. This pro- 
cedure is similar to INSERT _ND (Figures 2.10A and 
2.10B) but does not require an argument for the insertion 


_ position, since the first position is always implied. 


Although INSERT _ FD is not essential when 
INSERT_ND is available, it is convenient to use when 
insertions frequently occur at the front of lists. 

Figure 2.10G contains examples of the procedure. 


INSERT _LD Subroutine Figures 2.10E and 2.10F present 
the INSERT _LD subroutine procedure, which inserts a 
data item into the last position of a data list. This pro- 
cedure is similar to INSERT_FD (Figure 2.10C and 
2.10D) but deals with the last rather than the first position 
of a list. 

Figure 2.10G contains examples of the procedure. 


INSERT_ND1 Subroutine Figures 2.10H and 2.101 pres- 
ent the INSERT ND1 procedure, which produces the 
same results as INSERT _ND (Figures 2.10A and 2.10B). 
The main difference between the two procedures is that 
INSERT_ND1 does not use > other list-processing pro- 
cedures. 


INSERT_ND: 


: PROCEDURE(LISTeNeD) 3 
INSERT_ND Subroutine CLARE (LISTeNeD)5 


N FIXED DECIMAL(5), 
Purpose D CHARACTER(1), 
. : ; cist (P,Q) POINTER, 
To insert a data item into the nth position of a (LIST, ADDRESS1, ADDRESS2, AVAIL 
data list EXTERNAL) POINTERS 
4* TF LIST OF AVAILABLE STORAGE 
COMPONENTS IS EMPTY THEN PRINT 





Reference MESSAGE AND RETURN. */ 
INSERT_ND(LIST, N, D) IF 
AVAIL = NULL 
. THEN 
Entry-Name Declaration DO; 
DECLARE INSERT_ND PuT 
‘ ' EMPTY"); 
CHARACTER(1)); RETURN; 
END; 
; /* ASSIGN DATA ITEM TO FIRST 
Meaning of Arguments — | COMPONENT IN LIST OF AVAILABLE 
LIST --the pointer variable that is the head of the STORAGE. */ 
ed ok : : 4* IF LIST IS NULL OR N<2y_y INSERT 
N — --the position in the list where the data item FIRST COMPONENT OF AVAIL INTO FIRST 
is to be inserted POSITION OF LIST ANDO RETURN. */ 
D --the data item to be inserted IF 
(LIST = NULL) T(NK<K2) 
THEN 
Remarks 00; 
When the list is null or N is less than two, the data ADDRESS] = LISTS LIST = AVAILS 
: me Ae : ; so: ‘ AVAIL = ADDRESS_N(AVAIL,2)3 
item is inserted into the first position of the list. CALL SET_POINTER(LIST,ADDRESS1)3 
When N exceeds the size of the list, the data item RETURNS 
is inserted into the last position. N cannot have a END; IF 
value greater than 99999. N > SIZE(LIST) 
THEN 
Other Programmer-Defined Procedures Required eee P = LIST: 
ADDRESS_N,SET_DATA, SET_ POINTER, and DO : 
SIZE WHILE(P -= NULL);$ 
Q= P$ P = Q=>POINTERS 
ENO$ 
Method P, Q—->POINTER = AVAIL; 
This subroutine does not destroy data previously in see ADDRESS_NCAVAIL» 2)3 
the list. When an item is inserted, the size of the list RETURN; INTER SNUCES 
increases by one. The item previously in the nth END; 
position becomes the (n+1)th item. The value of D /* OTHERWISE OBTAIN THE ADDRESS OF 
: ted. if h t , d THE N-TH COMPONENT OF LIST. */ 
is converted, if necessary, to a character string, an ADDRESS2 = ADDRESS_N(LIST»N): 
the leftmost character of the string is inserted into ADDRESS1 = ADORESS_N(LIST,N—1)3 
the list. /* INSERT FIRST COMPONENT OF AVAIL 
INTO THE N-TH POSITION OF LIST. */ 
CALL SET_POINTER(AODDRESS1, AVAIL)$ 
ADDRESS1 = AVAIL: 
Figure 2.10A. Description of the INSERT _ND subroutine for AVAIL = ADDRESS_N(AVAIL»2)5 
inserting a data item into the nth position of a CALL SET_POINTER(ADORESS1,ADORESS2)5 
data list END 


INSERT_ND; 


Figure 2.10B. Inserting a data item into the nth position of a data 
list 
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INSERT_FD Subroutine 


Purpose 
To insert a data item into the first position of a. 
data list 


Reference 
INSERT_FD(LIST, D) 


Entry-Name Declaration 
DECLARE INSERT_FD 
ENTRY(POINTER, CHARACTER(1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
D --the data item to be inserted 


Remarks 
When the list is null, the data item is inserted into 
the first position of the list. 


Other Programmer-Defined Procedures Required 
INSERT_ND 


Method | 
This subroutine uses the INSERT_ND procedure 
with N equal to one: 
CALL INSERT_ND(LIST, 1, D); 





Figure 2.10C. Description of the INSERT_FD subroutine for 
inserting a data item into the first position of a 
data list 


INSERT_FO: 

PROCEDURE (LIST,D)5 
DECLARE 

LIST POINTER, 

OD CHARACTER(1)5 

CALL INSERT_LND(LIST,1,0)3 


ENO 
INCERT FNS 


Figure 2.10D. Inserting a data item into the first position of a 
data list 
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INSERT_LD Subroutine 


Purpose 
To insert a data item into the last position of a data 
list 


Reference 
INSERT_LD(LIST, D) 


Entry-Name Declaration 
DECLARE INSERT_LD 
ENTRY(POINTER, CHARACTER (1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
D --the data item to be inserted 


Remarks 
When the list is null, the data item is inserted into 
the first position of the list. 


Other Programmer-Defined Procedures Required 
INSERT_ND 


Method 
This subroutine uses the INSERT_ND procedure 
with N equal to 99999, which forces the item to be 
inserted into the last position of the list: 


CALL INSERT_ND(LIST, 99999, D); 





Figure 2.10E. Description of the INSERT _LD subroutine for 
inserting a data item into the last position of a 
— data list 


INSERT_LD? 

PROCEDURE(LIST,»D)3 
DECLARE 

LIST POINTER, 

DO CHARACTER(1)$ 

CALL INSERT_ND(LIST,»99999,0)5 
END 

INSERT_LO; 


Figure 2.10F. Inserting a data item into the last position of a data 


list 


Data List 
(before reference) Subroutine Reference 


Li: | Let] besy INSERT_ND(L1,1,’A’) Lt: 





INSERT_ND(L1,2,‘A’) Lt: 
INSERT_ND(L1,3,'A’) Be 
INSERT_ND(L1,9,'A’) Lt: 
INSERT _ND(L1,-3,’A’) | L1: 
INSERT_FD(L1,‘A’) Lt: 
INSERT_LD(L1,‘A’) L1: 
INSERT_ND(L2,1,‘6’) L2: 
INSERT_ND(L2,2,’6’) L2: 
INSERT_FD(L2,‘*’) L2: 
INSERT_LD(L2,‘*’) L2: 





Data List 
(after reference) 


| FOAL Pelt] PSN 


Figure 2.10G. Examples of references to the INSERT ND, INSERT FD, and INSERT _LD subroutines 
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INSERT _ND1 Subroutine 


Purpose 
To insert a data item into the nth position of a 
data list 


Reference 
INSERT_ND1(LIST,N, D) 


Entry-Name Declaration 
DECLARE INSERT_ND1 
ENTRY(POINTER, FIXED DECIMAL(5), 
CHARACTER (1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N --the position in the list where the data item 
is to be inserted 
D --the data item to be inserted 


Remarks 
When the list is null or N is less than two, the data 
item is inserted into the first position of the list. 
When N exceeds the size of the list, the data item 
is inserted into the last position. N cannot have a 
value greater than 99999. 


Other Programmer-Defined Procedures Required 
None 


Method 
This subroutine does not destroy data previously 
in the list. When an item is inserted, the size of the 
list increases by one. The item previously in the 
nth position becomes the (n+1)th item. The value 
of D is converted, if necessary, to a character 
string, and the leftmost character of the string Is 
inserted into the list. 





Figure 2.10H. Description of the alternative subroutine 
INSERT ND1 
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INSE 


RT_NDI: 
PROCFDOURFI(LIST,N,D)3 


DECLARE 


I 


DO 


END; 


I 


DO 


ENDs 


DO 


END; 


END 


(NoIT) FIXED DECIMAL(5), 
D CHARACTER(1), 

(LIST, ADORESSI, AVAIL 

POINTER, 

ADORESS2 POINTER, 

1 COMPONENT BASEDCADDRESS2)>5 

2 DATA CHARACTER(1), 

2 POINTER POINTERS 

/* IF LIST OF AVAIL2 STORAGE 
COMPONENTS IS EMPTY THEN PRINT 

MESSAGE ANDO RETURN. */ 


EXTERNAL ) 


F 
AVAIL = NULL 

THEN 

’ 

PUT 
LISTC®AVAIL 
RETURNS 


STORAGE IS EMPTY')$ 


/* ASSIGN CATA ITEM TO FIRST 
COMPONENT IN LIST OF AVAIL 
STORAGE. */ 
AVAIL->DATA = D3 
/* IF LIST IS NULL OR N<2_ INSERT 
FIRST COMPONENT OF AVAIL INTO 
FIRST POSITION OF LIST AND 
RETURN. */ 

F 
(LIST = NULL)IJ(N<2) 

THEN 

9 
ADDRESS1 = LIST; LIST = AVAIL; 
AVAIL = AVAIL->POINTER3 
LIST->POINTER = ADORESS1; 
RETURN; 


/* OTHERWISE, OBTAIN THE ADDRESS OF 
THE N-TH COMPONENT OF LIST. */ 
ADDRESS2 = LISTs I = 23 


WHILE ( (ADORESS2->POINTER~=NULL) €& 
CI<N)D5 
ADDRESS2 = ADDRESS2->POINTER; 

I= 1+ 135 

4* INSERT FIRST COMPONENT OF AVAIL 
INTO THE N-TH POSITION OF LIST. */ 
ADDRESS1 = ADDRESS2->POINTERS; 
ADDRESS2->POINTER = AVAIL; 

AVAIL = AVAIL~>POINTERS; 

ADDRESS2 = ADDRESS2->POINTERS 
ADORESS2->POINTER = ADDRESS13 


INSERT_NO1S$ 


Figure 2.101. An alternative subroutine for inserting a data item 


into the nth position of a data list 


Getting the Values of Data Items in Data Lists 


Once a data item has been inserted into a list, a common 
operation is to retrieve the item from the list. The follow- 
ing discussions develop four function procedures for ob- 
taining the values of data items at specified list positions: 

1. GET_ND, which gets the value of the data item in 
the nth position of a data list 

2. GET_ FD, which gets the value of the data item in 
the first position of a data list 

3. GET_LD, which gets the value of the data item in 
the last position of a data list 

4. GET_ND1, which produces the same results as 
GET_ND but does not use other list-processing pro- 
cedures 


GET_ND Function Figures 2.11A and 2.11B present the 
GET_ND function procedure, which gets the value of the 
data item in the nth position of a data list. Examples of 
references to the procedure appear in Figure 2.11G. 
GET_ND uses two arguments: a data list and the posi- 
tion of a data item in the list. The data item remains in the 
list after the value of the item is returned by GET_ND. 


GET _FD Function Figures 2.11C and 2.11D present the 
GET_FD function procedure, which gets the value of the 
data item in the first position of a data list. Figure 2.11G 
contains examples of the procedure. 

GET_FD is similar to GET_ ND (Figures 2.11A and 
2.11B) but does not require an argument to specify the 
item position, because the first position is always implied. 


GET_LD Function Figures 2.11E and 2.11F present the 
GET_LD function procedure, which gets the value of the 
data item in the last position of a data list. Examples of 
the procedure appear in Figure 2.11G. 

GET_LD is similar to GET FD (Figures 2.11C and 
2.11D) but deals with the last rather than the first position 
of a list. 


GET_ND1 Function Figures 2.11H and 2.111 present the 
GET _ND1i function procedure, which produces the same 
results as GET _ND (Figure 2.11A and 2.11B). The main 
difference between the two procedures is that GET ND1 
does not use other list-processing procedures. 





GET_ND Function 


Purpose 
To get the value of the data item in the nth 
position of a data list 


Reference 
GET_ND(LIST, N) 


Entry-Name Declaration 
DECLARE GET_ND ENTRY(POINTER, 
FIXED DECIMAL(5)) 
RETURNS(CHARACTER(1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N --the position of the data item whose value 
is to be obtained 


Remarks 
A value of N less than one or greater than the number 
of data items in the list causes a blank character to 
be returned. 


Other Programmer-Defined Procedures Required 
ADDRESS_N and GET_DATA 


Method 
The following reference obtains the value of the 
nth item: 


GET_DATA(ADDRESS_N(LIST, N)) 


The nth item remains in the list after its value is 
returned. 


Figure 2.11A. Description of the GET ND function for 
getting the data item in the nth position of 
a data list 
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GET_ND: 
PROCEDURE (LIST, N) 
RETURNS (CHARACTER(1))3 
DECLARE 
LIST POINTER, 
N FIXED DECIMAL(5)3 


RETURN(GET_DATA(CADORESS_N(LIST ND D238 | 


ENO 
GET_ND$ 


Figure 2.11B. Getting the data item in the nth position of a data 
list 


GET_FD Function 


Purpose 
To get the value of the data item in the first 
position of a data list 


Reference 
GET_FD(LIST) 


Entry-Name Declaration 
DECLARE GET_FD ENTRY(POINTER) — 
RETURNS(CHARACTER(1)); 


Meaning of Argument 
LIST --the pointer variable that is the head of the 
list to be processed 


Remarks 
A null value for LIST causes a blank character to be 
returned. 


Other Programmer-Defined Procedures Required 
GET DATA 


Method 
The following reference obtains the value of the 
first item: 


GET_DATA(LIST) 


The first item remains in the list after its value is 
returned. 





Figure 2.11C. Description of the GET _FD function for getting 
the data item in the first position of a data list 
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PROCEDURE (LIST) 

RETURNS (CHARACTER(1)93 
DECLARE 

LIST POINTERS 

RETURN(GET_DATA(LIST))3 
END 

GET_FD$ 


Figure 2.11D. Getting the data item in the first position of a data 


list 


GET_LD Function 


Purpose | 
To get the value of the data item in the last position 
of a data list 


Reference 
GET_LD(LIST) 


Entry-Name Declaration 
DECLARE GET_LD ENTRY(POINTER) 
RETURNS(CHARACTER(1)); 


Meaning of Argument 
LIST --the pointer variable that is the head of the 


list to be processed 


| | Remarks 


A null value for LIST causes a blank character to be 
returned. 


Other Programmer-Defined Procedures Required 
GET _DATA and ADDRESS_ NEXT 


Method 
The ADDRESS_NEXT function is used to progress 
“through the list to the last component. The 
GET_DATA function then obtains the data value in 
the last component. The last item remains in the list 
after its value is returned. 





Figure 2.11E. Description of the GET LD function for getting 
the data item in the last position of a data list 


GET_LD: 
PROCEDURE (LIST) 
RETURNS (CHARACTER(1))3 
DECLARE 
(LIST, AOORESS1, ADDRESS2) POINTER? 
ADDRESS1, AOORESS2 #®= LIST$ 


00 
WHILE (ADDRESS2—8NULL) $ 
AOORESS1 = AODRESS2; 
ADDRESS2 = ADDRESS_NEXT(ADORESS2) 3 
END3 
RETURN(GET_DATA(ADORESS1))$ 
END 


GET_LDO$ 


Figure 2.11F. Getting the data item in the last position of a data 
list 


Function Function 
Data List Reference Value 


L1: 


L1: 


L1: 


L1: 


L1: 


ea 


L1: 


L2: 


L2: 


L2: 


L2: 





ThE REL RBL AO LRHEN GET ND(L1,1) 
AL Peel bela] bet Pe GET_ND(L1,5) 


LbeLbEL BEL boOL REN GET_ND(L1,3) 
| boLAL EEL bo | OT bEN GET_ND(L1,0) 
[ bela] bel-] bole] be] bee NX GET_ND(L1,9) 


OAL beret bole] pelt beLN) [| GET_Fp(L1) 
C bef4L_ bE B} teil bee GET _LD(L1) 


GET_ND(L2,1) 
GET_ND(L2,0) 
GET_FD(L2) 


GET_LD(L2) 


Figure 2.11G. Examples of references to the GET _ND,GET FD, and GET LD functions 
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GET_ND1 Function 


Purpose 
To get the value of the data item in the nth position 
of a data list 


Reference 
GET_ND1(LIST, N) 


Entry-Name Declaration 
DECLARE GET_ND1 ENTRY(POINTER, 
FIXED DECIMAL(5)) 
RETURNS(CHARACTER(1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N --the position of the data item whose value 
is to be obtained 


Remarks 
A value of N less than one or greater than the number 
of data items in the list causes a blank character to be 
returned. i 


Other Programmer-Defined Procedures Required 
None 


Method 
The nth data item remains in the list after its value is 
returned. 


Figure 2.11H. Description of the alternative functionGET ND1 
for getting the data item in the nth position of a 
data list 
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GET_ND1: 
PROCEDURE (LIST, N) 
RETURNS (CHARACTER(1))3 
DECLARE 
LIST POINTER, 
ADDRESS POINTER, 
(NeI) FIXED DECIMAL(5), 
1 COMPONENT BASED(AODRESS), 
2 DATA CHARACTER(1), 
2 POINTER POINTER; 
IF 
(LIST = NULL) I(NCK1) 
THEN 
RETURN(* *)3 
ADDRESS = LIST3$ 


DO 
I = 1 BY 13 
IF 
(ADDRESS=>POINTER = NULL) & 
(I-=N) 
THEN 
RETURN(® *)3 
IF 
I =N 
THEN 
RETURN( ADORESS->DATA)3 
ADDRESS = ADDRESS=—>POINTER; 
END; 
ENO 


GET_ND1; 


Figure 2.111. An alternative method for obtaining the value of the 
nth data item in a data list 


Deleting Data Items from Data Lists 


After a data item has been inserted into a list, it may be 
necessary to delete the item from the list. The following 
discussions develop four subroutine procedures for delet- 
ing data items from specified list positions: 

1. DELETE_ND, which deletes the data item in the 
nth position of a data list 

2. DELETE_FD, which deletes the data item in the 
first position of a data list 

3. DELETE_LD, which deletes the data item in the 
last position of a data list 

4. DELETE ND1, which is equivalent to 
DELETE _ ND but does not use other list-processing pro- 
cedures 


These procedures return the deleted storage to the list of 
available storage components, AVAIL. 


DELETE _ND Subroutine Figures 2.12A and 2.12B pres- 
ent the DELETE ND subroutine procedure, which deletes 
the data item in the nth position of a data list. Examples 
of the procedure appear in Figure 2.12G. 


DELETE ND Subroutine 


Purpose 
To delete the data item in the nth position of a data 
list 


Reference 
DELETE ND(LIST, N) 


Entry-Name Declaration 
DECLARE DELETE_ND ENTRY(POINTER, 
FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the list 
to be processed 
N --the position of the data item to be deleted 


Remarks 
No data item is deleted when the value of N is less 
than one or greater than the number of items in the 
list. 


Other Programmer-Defined Procedures Required 
ADDRESS_N and SET_POINTER 


Method | 
The nth component of LIST is deleted from LIST 
and inserted in the list of available storage 
components, AVAIL. The size of LIST is decreased 
by one, and that of AVAIL is increased by one. 





Figure 2.12A. Description of the DELETE _ND subroutine for 
deleting the data item in the nth position of a 
data list 


DELETE_ND: 


PROCEDURE (LIST »N)$ 


DECLARE 


N FIXED DECIMAL(5), 
(LIST»ADDRESS1,ADDRESS2,ADDRESS3y 
AVAIL EXTERNAL) POINTER? 
/* IF LIST IS EMPTY OR N IS LESS 
THAN 1, THEN RETURN. */ 

IF 
(LIST = NULL)I(N<1) 

THEN 
RETURN: 
/* DELETE FIRST COMPONENT IF N 
EQUALS 1. */ 

IF 
N= 1 

THEN 

D0; 
ADDRESS2 = LIST3 
LIST = ADORESS_N(LIST»2)3 
GO TO 

L3 


END$ 


Ls 


ENO 


/* OBTAIN N-TH COMPONENT. */ 
ADDRESS2 = ADDRESS_N(ILIST ND? 
IF 

ADORESS2 # NULL 

THEN 
RETURN} 
ADORESS1 = ADORESS_N(LIST N—1)3 
ADDRESS3 = ADDRESS_NILIST N41)3 
/* DELETE N-TH COMPONENT. *#/ 
CALL SET_POINTER(ADDRESS1,ADDRESS3)3 
/* INSERT OELETED COMPONENT INTO 
LIST OF AVAILABLE STORAGE 
COMPONENTS. */ 


AODRESS1 = AVAIL3 
AVAIL = ACORESS23 


CALL SET_POINTER(AVAIL, ADDRESS1)3 


DELETE_ND3; 


Figure 2.12B. Deleting the data item in the nth position of a data 


list 


DELETE ND uses two arguments: a data list and the 


position of a data item in the list. The size of the list de- 
creases by one after deletion occurs, and the list of avail- 
able storage components, AVAIL, acquires the storage 
component used by the deleted item. 
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DELETE _FD Subroutine Figures 2.12C and 2.12D pres: _ 
ent the DELETE_FD subroutine procedure, which deletes 
the data item in the first position of a data list. Figures 
2.12G contains examples of the procedure. | 
DELETE_FD is similar to DELETE_ND (Figures 
2.12A and 2.12B) but does not use an argument to specify 
the item position, since the first position is always implied. 


DELETE _FD Subroutine 


Purpose 
To delete the data item in the first position of a 
data list 


Reference | 
DELETE _FD(LIST) 


Entry-Name Declaration 
DECLARE DELETE_FD ENTRY(POINTER); 


Meaning of Argument 
LIST --the pointer variable that is the head of the list 
to be processed 


Remarks 
No data item is deleted when LIST is null. 


Other Programmer-Defined Procedulgs Required 
DELETE _ND 


Method 
The following reference is used: 


DELETE_NDILIST, 1) 


Figure 2.12C. Description of the DELETE FD subroutine for 
deleting the data item in nthe ‘first position of a 
data list 


DELETE_FOS 
PROCEOURE (LIST) 
DECLARE | : 7 
LIST POINTERS | 
CALL DELETE_ND(LIST,1)3 
END | : 
DELETE_FD$ 


Figure 2.12D. Deleting the data item in the first position of adata 


list 
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| DELETE _LD Subroutine Figures 2.12E and 2.12F pres- 


ent the DELETE _LD subroutine procedure, which deletes 
the data item in the last position of a data list. This pro- 
cedure is similar to DELETE_FD (Figures 2.12C and 


 2.12D) but deals with the last rather than the first position 


of a list. | 
_ Figure 2.12G contains an example of reference to the 
procedure. 


| DELETE _LD Subroutine 


Parsee -_ 
To delete the data item in the last position of a data 
list 


Reference 
-DELETE_LD(LIST) 


Entry-Name Declaration 
DECLARE DELETE LD ENTRY(POINTER); 


Meaning of Argument 
LIST --the pointer variable that is the head of the list. 
to be processed 


Remarks | 
No data item is deleted when LIST is null. 


| Other peeumnen Defined Procedures nodes 


(DE a ND and SIZE 


. {Method | | 


The following reference is used: 


- DELETE_ND(LIST, SIZE(LIST)) 





Figure 2. 12k, Description of the DELETE _LD subroutine for 


deleting the data item in the last position of a 
data list 


DELETE_LO: 
| PROCEDURE (LIST); 
DECLARE 
LEST POINTER: 
CALL DELETE_NDILIST, SEZECLIST)D3 
END 
DELETE_LO; 


‘Figure 2.12F. Deleting the data item in the last position of a data 
list 


Data List Data List 
(before reference) Subroutine Reference (after reference) 


4 CREE HED EN | octets now 






DELETE _ND(L1,2) 
DELETE _ND(L1,3) 
DELETE ND(L1,5) 


DELETE _ND(L1,—2) 





Li: DELETE _FD(L1) 
Lt: DELETE LD(L1) 
L2: DELETE _ND(L2,1) 


DELETE ND(L2,0) 


DELETE _FD(L2) 





DELETE LD(L2) 











Figure 2.12G. Examples of references to the DELETE ND, DELETE FD, and DELETE LD subroutines 
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DELETE NDI Subroutine Figures 2.12H and 2.121 pres- 
ent the DELETE _ND1 subroutine procedure, which pro- 
duces the same results as DELETE ND (Figures 2.12A 
and 2.12B). The main difference between the two pro- 
cedures is that DELETE NDI does not use other list- 
processing procedures. 


DELETE_ND1 Subroutine 


Purpose 
To delete the data item in the nth position of a 
data list 


Reference 
DELETE ND1(LIST, N) 


Entry-Name Declaration 
DECLARE DELETE_ND1 ENTRY(POINTER, 
FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N --the position of the data item to be deleted 


Remarks 
No data item is deleted when the value of N is less 
than one or greater than the number of items in the 
list. 


Other Programmer-Defined Procedures Required 
None 7 


Method 
| The nth component of LIST is deleted from LIST 
and inserted in the list of available storage 
components, AVAIL. The size of LIST is decreased 
by one, and size of AVAIL is increased by one. 





Figure 2.12H. Description of the alternative subroutine 
DELETE ND1 for deleting the data item in 
the nth position of a data list 
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ODELETE_NOL: 
PROCEOURE(LIST.ND3 
DECLARE 
(NeoI) FIXED DECIMAL(5), 
(LIST,ADDRESSIL AVAIL EXTERNAL) 
POINTER, 
ADDRESS2 POINTER, 
1 COMPONENT BASED(ADDRESS2), 
2 DATA CHARACTER(1), 
2 POINTER POINTER? 
/* IF LIST IS EMPTY OR WN IS LESS 
THAN 1, THEN RETURN. */ 
IF 
(LIST = NULLDIYPCN<C1]) 
THEN 
RETURNS 
/* OELETE FIRST COMPONENT IF WN 
EQUALS I. #/ 
ADORESS2 = LIST; 


N=] 


LIST = ADDORESS2—>POINTERS 
GO To 
L3 
END; 
/* OBTAIN N-TH COMPONENT. %/ 
AODRESS1' = LIST; I = l3 
DO WHILE! (( ADDRESS2—>POINTER~2NULL) 
ECI<ND D3 1 
ADDRESS1 '= ADORESS23 
ADDRESS2 = ADORESS2->POINTER: 
I2 ft ¢#i3 


ENO3: 


IF 
(ADORESS2-—->POINTER #@= NULL) & 
(I-2N) 
THEN 
RETURNS 
4* DELETE N-TH COMPONENT. %/ 
ADDRESS1—->POINTER = 
ADDRESS 2—>POINTER?3 
/* INSERT DELETED CORPONENT INTO 
LIST OF AVAILABLE STORAGE 
COMPONENTS. %/ 
L: 
ADDRESS] = AVAIL? 
AVAIL = ADORESS23 
ADDRESS2->POINTER = ADORESSIL 
END 
DELETE_ND13 


Figure 2.121. An alternative subroutine for deleting the data item 


in the nth position of a data list 


Removing Data Items from Data Lists 


A frequent combination of operations on a list involves 
getting the value of a data item and then deleting the item 
from the list. This combination is referred to as removing a 
data item from a list and may be implemented as a single 
function procedure. The following discussions develop 
three functions for removing data items from specified list 
positions: 

1. REMOVE_ND, which gets and deletes the data item 
in the nth position of a data list 

2. REMOVE _ FD, which gets and deletes the data item 
in the first position of a data list 

3. REMOVE _LD, which gets and deletes the data item 
in the last position of a data list 


REMOVE_ND Function Figures 2.13A and 2.13B pres- 
ent the REMOVE _ ND function procedure, which gets and 
deletes the data item in the nth position of a data list. 
Examples of the procedure appear in Figure 2.13G. 























REMOVE_ND Function 






Purpose 
To get and delete the data item in the nth position 
of a data list 





Reference 
REMOVE_ND(LIST,N) 






Entry-Name Declaration 
DECLARE REMOVE_ND ENTRY(POINTER, 
FIXED DECIMAL(5)) 

RETURNS(CHARACTER(1)); 





Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N --the position of the data item to be removed 





Remarks 
When the value of N is less than one or greater than 
the number of data items in the list, no data item 

is deleted from the list, and a blank character is 

returned. 


Other Programmer-Defined Procedures Required 
GET NDand DELETE ND 





Method 
This function combines the operations of the 
GET ND and DELETE_ND procedures. 


Figure 2.13A. Description of the REMOVE ND function for 
removing the data item in the nth position of a 
data list 





REMOVE_ND:?: 
PROCEDURE (LISTs» N) 
RETURNS (CHARACTER(1))3 

DECLARE 
LIST POINTER, 
N FIXED DECIMAL(5), 
D CHARACTER(1)3 
D = GETUND(LIST»N); 
CALL DELETE_ND(LIST,N); 
RETURN(O)$ 

END 
REMOVE_ND3$ 


Figure 2.13B. Removing the data item in the nth position of a 
data list 


REMOVE_ND uses two arguments: a data list and the 
position of a data item in the list. The size of the list de- 
creases by one afier the item is deleted and its value re- 
turned to the point of invocation. The list of available 
storage components, AVAIL, acquires the storage com- 
ponent used by the removed item. 


REMOVE _FD Function Figures 2.13C and 2.13D present 
the REMOVE _FD function procedure, which gets and 
deletes the data item in the first position of a data list. 
Figure 2.13G contains examples of the procedure. 

REMOVE _FD is similar to REMOVE _ ND (Figures 
2.13A and 2.13B) but does not require an argument to 
specify the item position, since the first position is always 
implied. 


REMOVE_FD Function 


Purpose 
To get and delete the data item in the first position 
of a data list 


Reference 
REMOVE_FD(LIST) 


Entry-Name Declaration 
DECLARE REMOVE_FD ENTRY(POINTER) 


RETURNS(CHARACTER(1)); 


Meaning of Argument 
LIST --the pointer variable that is the head of the 
list to be processed 


Remarks 
When LIST is null, no data item is deleted from the 
list, and a blank character is returned. 


Other Programmer-Defined Procedures Required 
REMOVE _ND 


Figure 2.13C. Description of the REMOVE _ FD function for 
removing the data item in the first position of a 
data list 
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~REMOVE_FD: 
PROCEDURE (LIST) 
RETURNS (CHARACTER(1))3 
DECLARE 
LIST POINTERS 
RETURN(REMOVE_NO(LIST,1))35 
END 
REMOVE_FD$ 


Figure 2.13D. Removing the data item in the first position of a 
data list 


REMOVE _LD Function Figures 2.13E and 2.13F present 
the REMOVE _LD function procedure, which gets and 
deletes the data item in the last position of a data list. This 
procedure is similar to REMOVE_FD (Figures 2.13C and 
2.13D) but deals with the last rather that the first position 
of a list. | 
Examples of the procedure appear in Figure 2.13G. 


Replacing Data Items in Data Lists 


Replacing a data item in a data list involves changing an 
item already in the list. The following discussions develop 
three subroutine procedures for replacing data items in 
specified list positions: 

1. REPLACE _ ND, which replaces the data item in the 
nth position of a data list 

2. REPLACE _FD, which replaces the data item in the 
first position of a data list | 

3. REPLACE LD, which replaces the data item in the 
last position of a data list 


REPLACE _ND Subroutine Figures 2.14A and 2.14B 
present the REPLACE ND subroutine procedure, which 
replaces the data item in the nth position of a data list. 
Examples of the procedure appear in Figure 2.14G. 

REPLACE ND uses three arguments: a data list, the 
position of the data item to be replaced, and the new data 
item. The procedure combines a deletion and an insertion 
involving the nth position in the list. 


REPLACE _FD Subroutine Figures 2.14C and 2.14D 
present the REPLACE FD subroutine procedure, which 
replaces the data item in the first position of a data list. 
Figure 2.14G contains examples of the procedure. 


34 


REMOVE _LD Function 


Purpose 
To get and delete the data item in the last position 
of a data list 


Reference 
REMOVE_LD(LIST) 


Entry-Name Declaration 
~DECLARE REMOVE_LD ENTRY(POINTER) 
RETURNS(CHARACTER(1)); 


Meaning of Argument 
LIST --the pointer variable that is the head of the 
list to be processed 


Remarks 
When LIST is null, no data item is deleted from the 
list, and a blank character is returned. 


Other Programmer-Defined Procedures Required 
REMOVE_ND and SIZE 


Method 
The following reference is used: 


REMOVE_ND(LIST, SIZE(LIST)) 





Figure 2.13E. Description of the REMOVE _LD function for 
removing the data item in the last position of a 
data list 


REMOVE_LD: 
PROCEDURE (LIST) 
RETURNS (CHARACTER(1))3 
DECLARE 
LIST POINTERS 
RETURN(REMOVE_ND(LIST,SIZEC(LISTII$ 
ENO 
REMOVE_LD3 


Figure 2.13F. Removing the data item in the last position of a 
data list 


ce 


(before reference) Reference Value (after reference) 
REMOVE_ND(L1,1) a L1: 
REMOVE_ND(L1,2) ‘$" L1: 
REMOVE_FD(L1) ok Li: | bps) rain 
REMOVE_LD(L1) '2' L1: 
REMOVE _ND(L1,5) ‘0! L1: | bet Bly BN 
REMOVE_LD(L2) ‘b’ L2: 





. 
G 
= 
g 
= 
] S: 
Won Za 


Pet Peis] PIN 


Figure 2.13G. Examples of references to the REMOVE ND, REMOVE _ FD, and REMOVE _LD functions 


|REPLACE_ND Subroutine 


Purpose 
To replace the data item in the nth position of a 
data list 


Reference 
REPLACE ND(LIST,N, D) 


Entry-Name Declaration 
DECLARE REPLACE_ND 
ENTRY(POINTER, FIXED DECIMAL(5), 
CHARACTER(1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N --the position of the data item to be replaced 
D.__--the data item that replaces the nth data item 


| Remarks 
When N is less than one, the value of D becomes the 
first data item in the list. When N exceeds the size of 
the list, the value of D becomes the last item in the 
list. In both of these cases, the size of the list 
increases by one. In other cases, the size of the list 
remains unchanged. 


| Other Programmer-Defined Procedures Required 
DELETE ND and INSERT_ND 


| Method 
The nth data item in the list is deleted. Then the 
value of D is inserted into the nth position of the 
list. 





Figure 2.14A. Description of the REPLACE ND subroutine for 
replacing the data item in the nth position of a 
data list 


REPLACE_ND:PROCEDURE(LISTs Ny D)3 
DECLARE 

1 COMPONENT BASED(LIST); 

2 DATA CHARACTER(1)> 

2 POINTER POINTER, 

N FIXED DECIMAL(5); 

D CHARACTER(1)>, 

LIST POINTERS 

CALL DELETE_ND(LIST»N)$ 

CALL INSERT_ND(LIST,N,D)3$ 
END 

REPLACE_ND; 


Figure 2.14B. Replacing the data item in the nth position of a 
data list 


36 


REPLACE _FD Subroutine 


Purpose 
To replace the data item in the first position of a 
data list 


Reference 
REPLACE _FD(LIST, D) 


Entry-Name Declaration 
DECLARE REPLACE_FD 
ENTRY(POINTER, CHARACTER(1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
D --the data item that replaces the first data item 


Remarks 
When LIST is null, D is inserted into the list. 


Other Programmer-Defined Procedures Required 
REPLACE _ND 


Method 
The following reference is used: 


REPLACE_NDILIST, 1, D) 





Figure 2.14C. Description of the REPLACE FD subroutine for 
replacing the data item in the first position of a 
data list 


REPLACE_FD: 
PROCEDURE (LIST,D)3 
DECLARE 
LIST POINTER, 
D CHARACTER(1)3 
CALL REPLACE_NO(LIST,1,0)3 


REPLACE_FDO3 


Figure 2.14D. Replacing the data item in the first position of a 
data list 


REPLACE FD is similar to REPLACE ND (Figures 
2.14A and 2.14B) but does not require an argument for 
the item position, because the first position is always im- 
plied. 


REPLACE _LD Subroutine Figures 2.14E and 2.14F 
present the REPLACE LD subroutine procedure, which 
replaces the data item in the last position of a data list. 
This procedure is similar to REPLACE FD (Figures 2.14C 
and 2.14D) but deals with the last rather than the first 
position of a list. 

Examples of the procedure appear in Figure 2.14G. 


Searching for Data Items in Data Lists 


Table lookup operations are possible on data lists by per- 


forming serial searches through the lists for specified items. 


The following discussion develops the FIND_D function 
procedure, which performs such a search. 


FIND _D Function Figures 2.15A,2.15B, and 2.15C pres- 
ent the FIND _D function procedure, which searches a list 
for the first occurrence of a specified data item. FIND D 
uses two arguments: the data list to be searched and the 
data item to be searched for in the list. The value returned 
by the function is the position where the item first occurs 
in the list. A zero value indicates that the list does not 
contain the data item. 

Examples of the function procedure appear in Figure 
2.15C. 


REPLACE LD Subroutine 


Purpose 
To replace the data item in the last position of a 
data list 


Reference 
REPLACE LD(LIST, D) 


Entry-Name Declaration 
DECLARE REPLACE _LD 
ENTRY(POINTER, CHARACTER(1)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
D --the data item that replaces the last data item 


Remarks 
When LIST is null, D is inserted into the list. 


Other Programmer-Defined Procedures Required 
REPLACE ND and SIZE 


Method 
The following reference is used: 


REPLACE _ND(LIST, SIZE(LIST), D) 


Figure 2.14E. Description of the REPLACE LD subroutine 
for replacing the data item in the last position 
of a data list 


REPLACE_LD? 
PROCEDURE(LIST,0)3 
DECLARE 
LIST POINTER, 
D CHARACTER(1)3 
CALL REPLACE_NDILIST,SIZE(LISTI 093 
END 
REPLACE_LD3; 


Figure 2.14F. Replacing the data item in the last position of a data 
list 
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Data List Data List 
(before reference) Subroutine Reference (after reference) 


Li: | Fool Fez] Peo 
ur: | Feo] Fez] Fool 
: Lpo#l PieN 


2 | e#l Petel\ 


L3: 


M4 


L3: 


REPLACE _ND(L1,1,’$’) 
REPLACE _ND{(L1,3,‘0’) 
REPLACE _ND{(L2,0,'*’) 
REPLACE _ND(L2,3,'*') 
REPLACE_FD(L3,‘A’) 


REPLACE LD(L3,’A’) 











Figure 2.14G. Examples of references to the REPLACE ND, REPLACE FD, and REPLACE _LD subroutines 


FIND_D Function 


Purpose 
To find the position of the first occurrence of a 
specified data item in a data list 


Reference 
FIND_D(LIST, D) 


Entry-Name Declaration 
DECLARE FIND_D ENTRY(POINTER, 
CHARACTER(1)) 
RETURNS(FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be searched 
D --the data item that is to be searched for in 
the list 


Remarks 
When the list does not contain D, the function 


returns a zero value. 


Other Programmer-Defined Procedures Required 
GET DATA and ADDRESS_NEXT 


Method 


The ADDRESS_NEXT function obtains successive 


addresses of list components. The GET_DATA 
function obtains the value of the data element in 
successive list components. 





Figure 2.15A. Description of the FIND_D function for finding 


the position of a data item in a data list 


38 


FINO_O: 


DEC 


DO 


I 


END; 


END 


Figure 2. 


PROCEDURE (LIST, 0) 

RETURNS (FIXED DECIMAL(5))3 
LARE 

(LIST, AOORESS) POINTER, 

D CHARACTER(1),» 

I FIXED DECIMAL(5)$ 

ADORESS = LIST; 

I = 03 


WHILE (ADDRESS~=NULL) $ 
I=tI+i13 
F 
D = GET_DATA(ADDRESS) 
THEN 
RETURN(I)$ 
ADDRESS = ADDRESS_NEXTC ADDRESS) 3 


RETURN(0) 3 
FIND_O; 


15B. Finding the position of a data item in a data list 


Data List 


uo CbEDbELRCLPELHEN 
u: [ bis? bis] bE LD ReLbhEN 
uo CbEDbEDHCLHELHEN 


Function Function 
Reference Value 


FIND_D(L1,’$') 


FIND D(L1,’.") 


FIND D(L1,‘*") 


a | 


FIND D(L2,‘$’) 





Figure 2.15C. Examples of references to the FIND_D function 


Interchanging Data Items in Data Lists 


Reordering data items in a list is a common list-processing 
operation. The following discussion develops the SWAP 
subroutine procedure, which interchanges the data items at 
two specified positions in a list. 


SWAP Subroutine Figures 2.16A, 2.16B, and 2.16C pres- 
ent the SWAP subroutine procedure, which interchanges 
the positions of two data items in a list. The procedure 
uses three arguments: a data list, the position of one item, 
and the position of a second item. If an argument specifies 
a nonexistent list position, no interchange occurs. 

Examples of the subroutine procedure appear in Figure 
2.16C. 


Manipulating Sublists and Lists 


Most of the foregoing procedures apply to single data 
items and not to collections of items in a list. For example, 
the DELETE _ND subroutine (Figures 2.12A and 2.12B) 
deletes only one data item from a list. If all items are to be 
deleted, DELETE ND must be invoked repeatedly until 
the list becomes null. 

The following discussions develop procedures for ma- 
nipulating entire lists or portions of lists called sublists. 
The operations performed by these procedures fall into 
twelve general categories: 

Inserting sublists and lists into data lists 
Deleting sublists and lists from data lists 
Assigning sublists and lists to data lists 
Linking data lists 
Splitting data lists 
Catenating data lists 
Searching data lists for sublists 
Testing data lists for equality 

9. Comparing data lists (greater than, equal to, or 
less than) 

10. Reversing data lists 

11. Sorting data lists 

12. Converting character strings to and from data lists 


ONAN RW 


SWAP Subroutine 


Procedure 
To interchange the positions of the two data items 
in a data list 


Reference 
SWAP(LIST, N1, N2) 


Entry-Name Declaration 
DECLARE SWAP 
ENTRY(POINTER, FIXED DECIMAL(5), 
FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST --the pointer variable that is the head of the 
list to be processed 
N1 = _--the position of a data item in the list 
N2  --the position of another data item in the list 


Remarks 
N1 does not have to be less than N2. The list 
remains unchanged, however, when N1 or N2 
specifies a position outside the list or N1 equals N2. 


Other Programmer-Defined Procedures Required 
ADDRESS_N, GET_DATA, and SET_DATA 


Method 
ADDRESS_N obtains the addresses of the list 
components that contain the specified data items. 
GET_DATA obtains the values of the data items. 
SET_DATA assigns each data item to the list 
component of the other. 





Figure 2.16A. Description of the SWAP subroutine for 
interchanging data items in a data list 
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More compact programs can be written with these types SWAP: 
of procedures. They eliminate the additional statements 
needed to control the repeated invocation of procedures 


that process single data items. © 


Inserting Sublists and Lists into Data Lists 


PROCEDURE(LIST, Nl» N2)5 
DECLARE | ? 
D CHARACTER(1), 

(NL, N2) FIXED DECIMAL(S), 

(LIST, ADDRESS1, ADORESS2) POINTER: 
ADORESS1 = ADDRESS_N (LIST,NL)$ 


| IF | 
Data lists are frequently created or extended by copying 1 FO a 1 = NULL 
all or part of another list. The following discussions de- RETURNS 
velop two procedures for obtaining data items from one ADDRESS2 = ADDRESS_N(LIST.N2)3 
list and inserting them into another list: a 
| hae : , i | RE! N 
1. INSERT_ SUB, which inserts a portion of one list eaunoe Ener ingen 


into another list | | 
2. INSERT_LIST, which inserts a complete list of OD = GET_DATA (ADDRESS1); 
items into another list | 


Both procedures obtain storage from the list of available END 


storage components, AVAIL. 


RETURNS 

CALL SET_DATA (ADORESS], 
GET_DATA( ADDRESS2))3 | 
CALL SET_DATACADORESS2, 03 


SWAP; 


Figure 2.16B. Interchanging data items in a data list 


Data List Subroutine | Data List | 
(before reference) | Reference | | (after reference) 


L1: 


L1: 


L1: 


L1: 


L1: 


Lt: 


L2: 


| FerAl reel pec] PON 


ThA LMBELRMELMPN 


| eAL Fmel Feil PO 
| PeLAL Pee] Pec] PN 


VA 


iu: DbRLHMELMIcL HEN 


L1: 








SWAP(L1,1,4) 





SWAP(L1,4,1) 







SWAP(L1,2,3) L1: 







~ SWAP(L1,1,1). L1: 






SWAP (L1,0,1) L1: 


ui | PAL PBL Pcl PLOIN 


L2: 


SWAP (L1,1,5) 






SWAP(L2,1,1) 


Figure 2.16C. Examples of references to the SWAP subroutine 
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INSERT _SUB Subroutine Figures 2.17A and 2.17B pres- 
ent the INSERT SUB subroutine procedure, which inserts 
a portion of the data items in one list into another list. 
Examples of the procedure appear in Figure 2.17E. 


INSERT SUB Subroutine 


Purpose 
To insert a sublist into a list 


Reference 
INSERT SUB(LIST1, N1, LIST2, N2, L) 


Entry-Name Declaration 
DECLARE INSERT SUB 
ENTRY(POINTER, FIXED DECIMAL(5), 
POINTER, FIXED DECIMAL(5), 
FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST1 = ---the list into which the sublist is to be 
inserted 
N1 ---the position in LIST1 at which the sublist 
is to be inserted 
LIST2 = ---the list that contains the sublist 


N2 ---the position in LIST2 at which the sublist 
begins 
L ---the number of data items in the sublist 
Remarks 


If N1 is less than one, the sublist is inserted at the 
front of LIST1. If N1 exceeds the size of LIST1, 
the sublist is inserted at the end of LIST1. If L 
exceeds the size of LIST2, the sublist is extended with 
blank characters to give it a size of L; however, 
LIST2 is not changed. When N2 is less than one, 

the sublist contains 1-N2 leading blanks followed by 
the first (N2+L-1) characters of LIST2. When 
(N2+L-1) is greater than the size of LIST2, the 
sublist contains the last (SIZE(LIST2)-N2+1) 
characters of LIST2 followed by 
(L-(SIZE(LIST2)-N2+1)) blank characters. In all 
cases, the sublist contains L data items, and LIST2 
is not changed. 


Other Programmer-Defined Procedures Required 
INSERT_ND and GET_ND 


Method 
GET_ND obtains each sublist data item from 
LIST2, and INSERT_ND inserts each sublist data 
item into LIST 1. 


Figure 2.17A. Description of the INSERT SUB subroutine 
for inserting a sublist into a list 


INSERT_SUB? 
PROCEDURE (LISTLONLeLIST2eN2eL 13 
DECLARE 
(LISTL,LIST2) POINTER, 
(NeNLON2,0,1) FIXED OEC IMAL (5S)?3 


IF 
N1i<l 
THEN 
N = 13 
ELSE 
N = N13 
DO 
I = 0 TO t-13 
CALL INSERT_ND(LISTL, N + I, 
GET_LND(LIST2, N2 + TV 
ENO; 
END 


INSERT_SUB; 


Figure 2.17B. Inserting a sublist into a list 


INSERT_LIST Subroutine 


Purpose 
To insert a list into another list 


Reference 
INSERT _LIST(LIST1, N, LIST2) 


Entry-Name Declaration 
DECLARE INSERT_LIST 
ENTRY(POINTER, FIXED DECIMAL(5), 
POINTER); 


Meaning of Arguments 
LIST1 = --the list into which the second list is to be 
inserted 
N --the position in LIST1 at which the list is 
to be inserted 
LIST2  --the list to be inserted into LIST 1 


Remarks 
If N is less than one, LIST2 is inserted at the front 
of LIST1. If N is greater than the size of LIST 1, 
LIST2 is inserted at the end of LIST1. 


Other Programmer-Defined Procedures Required 
INSERT_SUB and SIZE 


Method 
The following reference is used: 


INSERT_SUB(LIST1, N, LIST2, 1, SIZE(LIST2)) 





Figure 2.17C. Description of the INSERT LIST subroutine for 
inserting a list into another list . 


INSERT_SUB uses five arguments: two data lists, the INSERT_LIST? 


insertion position in the first list, the retrieval position in ical (LESTL> No LIST2N3 
the second list, and the number of items to be inserted. (LISTL, LIST2) POINTER, 
The size of the first list increases by the number of N FIXED DECIMAL(5)3 | 
items inserted. The size of the second list remains un- CALL INSERT_SUB(LIST1, Ny LIST2y 1s 


SIZEC(LIST2)) 
changed. ; END , 


INSERTLLIST3 
INSERT _LIST Subroutine Figures 2.17C and 2.17D pres- 
ent the INSERT LIST subroutine procedure, which in- Figure 2.17D. Inserting a list into another list 
serts all the data items in one list into another list. Figure 
2.17E contains an illustration of the procedure. 










Data List 
(before reference) 


L1: i Al | Em Cc} DIN 
2 [bb LReLREA 
L3: 


Reference | (after reference) 
uw Dba ROL ReLPeBLeeLPeN 
tH LBL BBL BEL PN 
2 (bE bELbELHELbEN 
Lt: 
L3: 
Li: | FOAL Fee] felcl Peo. 









INSERT _SUB(L1,2,L2,1,2) 









INSERT _SUB(L2,2,L1,1,2) 





INSERT_SUB(L3,1,L1,2,2) 







INSERT_LIST(L2,3,L1) 





Figure 2.17E. Examples of references to the INSERT SUB and INSERT _LIST subroutines 
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INSERT _LIST is similar to INSERT _SUB (Figures 
2.17A and 2.17B) except that an entire list is inserted. As 
a result of this difference, INSERT LIST requires only 
three arguments: two lists and the insertion position in the 
first list. 


Deleting Sublists and Lists from Data Lists 


The following discussions develop two subroutine pro- 
cedures for deleting all or some of the items in a data list: 
1. DELETE SUB, which deletes a portion of a list 

2. DELETE_ LIST, which deletes a complete list 


The storage used by the deleted items is returned to the 
list of available storage components, AVAIL. 


DELETE _SUB Subroutine Figures 2.18A and 2.18B pres- 
ent the DELETE _ SUB subroutine procedure, which de- 
letes a portion of a list. Examples of the procedure appear 
in Figure 2.18E. 

DELETE SUB uses three arguments: a data list, the list 
position at which deletion starts, and the number of data 
items being deleted. 


DELETE _LIST Subroutine Figures 2.18C and 2.18D 
present the DELETE LIST subroutine procedure, which 
deletes all items from a list. Figure 2.18E contains an illus- 
tration of the procedure. 

DELETE _LIST is similar to DELETE _SUB (Figures 
2.18A and 2.18B) but uses only one argument: the list 
being deleted. 


Assigning Sublists and Lists to Data Lists 


The following discussions develop two subroutine pro- 
cedures for setting a data list equal to all or part of another 
list: 

1. ASSIGN SUB, which assigns a sublist to a list 

2. ASSIGN_ LIST, which assigns an entire list to an- 
other list 


The effect of these procedures is equivalent to deletion of 
the receiving list followed by insertion of a list. 


DELETE SUB Subroutine 


Purpose 
To delete a portion of a list 


Reference 
DELETE SUB(LIST,N, L) 


Entry-Name Declaration 
DECLARE DELETE _.SUB 
ENTRY(POINTER, FIXED DECIMAL(5), 
FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST --the list in which deletion is to occur 
N --the position in LIST at which deletion is to 
start 
L --the number of data items to be deleted 


Remarks 
Data items are deleted from position N to position 
(N+L-1) in LIST. When (N+L-1) exceeds the size of 
LIST, all data items from position N to the end of 
LIST are deleted. If N exceeds the size of LIST, no 
data items are deleted. If N is less than one, the 
first (N+L-1) data items are deleted provided 
(N+L-1) is not negative; if it is negative, no data 
items are deleted. 


Other Programmer-Defined Procedures Required 
DELETE ND 


Method 
The following reference is used: 


DELETE ND(LIST, N) 





Figure 2.18A. Description of the DELETE SUB subroutine 
for deleting a sublist from a data list 


OELETE_SUB: 
PROCEDURE(LIST»s Ne L)$ 
DECLARE 
(Ns Ly I) FIXED DECIMAL(5S), 
LIST POINTERS 


DO 
I =N TO (N+ L = 1)3 
CALL CELETE_ND(LIST, N)$ 
END; 
ENO 


DELETE_SUB$ 


Figure 2.18B. Deleting a sublist 
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DELETE_LIST Subroutine 


Purpose 
To delete an entire list 


Reference 
DELETE _LIST(LIST) 


Entry-Name Declaration 


DECLARE DELETE_LIST ENTRY(POINTER); DELETE_LIST? 


PROCEDURE (LIST)$ 
: OECLARE 
Meaning of Argument LIST POINTER; 
LIST --the list to be deleted CALL DELETE_SUB(LIST, ly» 
SIZE(LIST))3 
Remarks en 


LIST is null after deletion. 


DELETE_LIST; 


Other Programmer-Defined Procedures Required pigure: 2.18). Deleting 2 lst 


DELETE SUB and SIZE 


Method 
The following reference is used: 


DELETE_SUB(LIST, 1, SIZE(LIST)) 





Figure 2.18C. Description of the DELETE LIST subroutine 
for deleting a list 


Data List Subroutine Data List 
(before reference) Reference (after reference) 


DELETE SUB(L1,1,2) 


DELETE_SUB(L1,3,1) 


bg 
Es 
WA 


DELETE_SUB(L1,0,3) 


DELETE _SUB(L1,2,3) 


Ea 
V4 


DELETE _SUB(L1,1,3) 


VAN Aa 


DELETE_LIST(L1) 





Figure 2.18E. Examples of references to the DELETE SUB and DELETE LIST subroutines 
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ASSIGN _SUB Subroutine Figures 2.19A and 2.19B pres- 
ent the ASSIGN SUB subroutine procedure, which assigns 
a sublist to a list. Examples of the procedure appear in 
Figure 2.19E. 


ASSIGN_SUB Subroutine 


Purpose 
To assign a sublist to a list 


Reference 
ASSIGN SUB(LIST1, LIST2, N, L) 


Entry-Name Declaration 
DECLARE ASSIGN SUB 
ENTRY (POINTER, POINTER, FIXED DECIMAL 
(5), FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST1 = --the list to which the sublist is to be 
assigned 
LIST2 = --the list that contains the sublist 
N --the position in LIST2 at which the sublist 
begins 
L --the number of data items in the sublist 


Remarks 
LIST1 is deleted before it receives the sublist. The 
sublist is then inserted into LIST 1 according to the 
conventions of the INSERT SUB subroutine. 


Other Programmer-Defined Procedures Required 
DELETE_LIST and INSERT _SUB 


Method 
The following references are used: 


DELETE _LIST(LIST1) 
and 
INSERT _SUB(LIST1,1, LIST2, N, L) 





Figure 2.19A. Description of the ASSIGN SUB subroutine for 
assigning a sublist to a list 


ASSIGN_SUB: 
PROCEDURE(LIST1l,». LIST2s Ny LDS 
DECLARE 
(LISTL»LIST2) POINTER, 
(Nel) FIXED DECIMAL (5)$ 
CALL DELETE_LIST(LIST1L)$ 
CALL INSERT_SUB (LISTl,» ly» LIST2, 
Ne L)3 
ENO 
ASSIGN_SUB$ 


Figure 2.19B. Assigning a sublist to a list 


ASSIGN_SUB uses four arguments: a receiving list, a 
source list, the position in the source list at which the 
sublist begins, and the number of items in the sublist. The 
source list is not changed by the procedure. 


ASSIGN _LIST Subroutine Figures 2.19C and 2.19D pres- 
ent the ASSIGN _ LIST subroutine procedure, which sets 
one list equal to another. An illustration of the procedure 
appears in Figure 2.19E. 

ASSIGN _LIST is similar to ASSIGN SUB (Figures 
2.19A and 2.19B) but requires only two arguments: the 
receiving and source lists. 


ASSIGN_LIST Subroutine 


Purpose 
To assign one list to another list 


Reference 
ASSIGN LIST(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE ASSIGN_LIST ENTRY(POINTER, 
POINTER); 


Meaning of Arguments 
LIST1  --the list to which the second list is to be 
assigned 
LIST2  --the list to be assigned to LIST 1 


Remarks 
LIST1 is deleted before it is assigned the data items 
of LIST2. 


Other Programmer-Defined Procedures Required 
ASSIGN _SUB and SIZE 


Method 
The following reference is used: 


ASSIGN_SUB(LIST1, LIST2, 1, SIZE(LIST2)) 





Figure 2.19C. Description of the ASSIGN_ LIST subroutine for 
assigning a list to another list 


ASSIGN_LLIST: 
PROCEOURE(LIST1,. LIST2)3 
DECLARE 
(LISTL, LISTZ) POINTER; 
CALL ASSIGNISUB(LIST1L,» LIST2s- ls» 
SIZECLIST2))3 
ENO 
ASSIGN_LIST$ 


Figure 2.19D. Assigning a list to another list 
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Data List Subroutine Data List 
(before reference) : , Reference (after reference) 










ASSIGN_SUB(L1,L2,1,2) 


ASSIGN_SUB(L1,L2,1,3) Lt: Pte del eeN| | 
L2 
Ut: 
[ bl PBL PoiclN 









ASSIGN_SUB(L3,L2,2,2) 









ASSIGN_ SUB(L2,L1,2,3) 












[hE PeLPEN 
Lt: 






~ ASSIGN_LIST(L2,L1) 





Figure 2.19E. Examples of references to the ASSIGN_ SUB and ASSIGN _LIST subroutines. 


Linking Data Lists 


Two lists may be combined to form a single list. One way 
of performing this operation is to insert the items of one 
list at the end of another list and to delete the contributing 
list. A more efficient method involves direct linkage of one 
list behind another by address manipulation rather than 
data movement. This method is used in the following dis- 
cussion to develop the LINK subroutine procedure. 


LINK Subroutine Figures 2.20A, 2.20B, and 2.20C present 
the LINK subroutine procedure, which appends the data 
items of one list behind the items of another list. The 
subroutine uses two arguments: the data lists being linked. 
The appended list becomes null after LINK has been exe- 
cuted. 


Splitting Data Lists 


The reverse operation of linking two lists is to split a single 
list into two separate lists. The following discussion de- 
velops the SPLIT subroutine procedure for such an opera- 
tion. 


SPLIT Subroutine Figures 2.21A, 2.21B, and 2.21C pres- 
ent the SPLIT subroutine procedure, which divides a list 
into two lists. The subroutine uses three arguments: the 
list to be split, the position where the split is to occur, and 
the list that receives the split items. 


Catenating Data Lists 


When the LINK subroutine (Figures 2.20A through 2.20C) 
is used to link two data lists, both lists are modified by the 
subroutine. If the lists are to remain unchanged, LINK 
cannot be used. 

The following discussion develops the CATENATE 
subroutine procedure for creating a third list from the data 
items of two other lists. 


CATENATE Subroutine Figures 2.22A, 2.22B, and 2.22C 
present the CATENATE subroutine procedure, which links 
the data items of two lists to form a third list. The sub- 
routine uses three arguments: the two lists to be linked 
and the list that receives the linked items. 


LINK Subroutine 


Purpose 
To append the data items of one list at the end of 
another list 


Reference | 
LINK(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE LINK ENTRY(POINTER, POINTER); 


Meaning of Arguments 
LIST1  --the list to which the data items of the 
second list are appended 
--the list whose data items are appended to 
LIST1 


LIST2 


Remarks 
LIST2 is null after its data items are appended to 
LIST 1. 


Other Programmer-Defined Procedures Required 
ADDRESS_NEXT and SET_POINTER 


Method 
The ADDRESS_NEXT function is used to progress 
to the last component of LIST 1. 


The SET_ POINTER subroutine links the last 
component of LIST1 to the first component of 
LIST2. LIST2 is then set to null. 





Figure 2.20A. Description of the LINK subroutine for linking 
two lists 
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LINK: | | | 
PROCEDUREI(LISTI, LCIST2Z)3 


DECLARE 
(LISTL» LIST2, ADDRESS], ADORESS2) 
POINTERS 
IF 
LISTI # NULL 
THEN | 
003 
LISTL = LIST2$ LIST2 = NULL 
| RETURNS 
ENO; 
ADDRESS2 = LISTI3 
00 
WHILE (ADDRESS2~=NULL } 3 
ADORESS1 = ADORESS23 
ADORESS2 = ADORESS_NEXT (ADDRESS2)5 
ENO; : | 
CALL SET_POINTER(ADORESS1», LIST2)3 
| LIST2 = NULL; 
END 


LINKS 


Figure 2.20B. Linking two lists 


Data List 
(before reference) 


Lt: at Pe] Pes] PEN 
v2: [bla eM 
L3: N 








Data List 
(after reference) 


ua: DC RbLRheLbBL REL bel PBL REN 


~ L2: 


Subroutine 
Reference 








LINK(L1,L2) 






vd 


IN 
LINK(L2,L1) : No 
» Lal bs i] Pe] bist Pi4IA 


Be Oe Be LN 


LINK(L1,L3) 


LINK(L3,L2) 


| PAL Pel Pec 


Figure 2.20C. Examples of references to the LINK subroutine 


SPLIT Subroutine 


Purpose 
To divide a list into two lists 


Reference 
SPLIT(LIST1, N, LIST2) 


Entry-Name Declaration 
DECLARE SPLIT 
ENTRY(POINTER, FIXED DECIMAL(5), 
POINTER); 


Meaning of Arguments 
LIST1 = --the list that is to be split 
N --the position at which LIST 1 is to be split 
LIST2 = --the list to which the second portion of 
LIST 1 is to be assigned 


Remarks 
Before LIST 1 is split, LIST2 is deleted. Then the 
data items from position N to the end of LIST 1 
are removed from LIST1 and linked to LIST2. 
If N exceeds the size of LIST 1, no splitting occurs, 
but LIST2 is deleted. If N is less than or equal to 
one, all data items in LIST1 are linked to LIST2, 
and LIST1 is set to null. 


Other Programmer-Defined Procedures Required 
DELETE_LIST, ADDRESS_N, GET_POINTER, 
and SET_ POINTER 


Method 
DELETE LIST deletes LIST2. ADDRESS_N 
obtains the address of the (N-1)th component of 
LIST1. This pointer element is then assigned to 
LIST2, causing the second portion of LIST1 to 
be linked to LIST2. Finally, the pointer element 
in the (N-1)th component of LIST 1 is set to null. 





Figure 2.21A. Description of the SPLIT subroutine for 
splitting a list 


SPLIT: 
PROCEDURE(LIST1ls Ne LIST2)$ 
OECLARE 
(LISTlLe LIST2, P) POINTER, 
N FIXED DECIMAL(5)$ 
CALL DELETE_LIST(LIST2)$ 


IF 
(N<=1) 
THEN 
DO; 
LIST2 = LISTL$ LIST = NULLS 
RETURNS 
END; 
P = ADDRESS_NILIST1ls N — 133 
IF 
(P = NULL) 
THEN 
RETURNS; 
LIST2 = GET_POINTER(P)$ 
CALL SET_POINTER(P NULL) 3 
END 


SPLITS 


Figure 2.21B. Splitting a list 
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Data List 
(before reference) 





Li: || 


La; | ex, POLYL PZ 
L3: NX 
Subroutine Data List 
Reference (after reference) 
SPLIT(L1,5,L3) L1: | -er1] Hela] best beak 
Ls: | eal Fey PiclN 
SPLIT(L1,5,L2) Li: | Eri] Fert bes] bela 
vz: [bl PBL bicKXk 
SPLIT(L2,1,L3) L2: NX 
Ls: | ex] POLY, RIZIN 
SPLIT(L3,1,L2) L2: 
L3: 


Figure 2.21C. Examples of references to the SPLIT subroutine 


CATENATE Subroutine 


Purpose 
To form a third list by linking the data items of two 
other lists 


Reference 
CATENATE(LIST1, LIST2, LISTS) 


Entry-Name Declaration 
DECLARE CATENATE 
ENTRY(POINTER, POINTER, POINTER); 


Meaning of Arguments 
LIST1 = --the first list to be linked 
LIST2 _ --the list to be linked behind LIST 1 
LIST3  --the list to which the linked data items of 
LIST 1 and LIST2 are assigned 


Remarks 
Any two or all three list arguments may be the same 
list. LIST1 and LIST2 are not changed when LIST3 
is different from LIST1 and LIST2. 


Other Programmer-Defined Procedures Required 
INSERT_LIST, ASSIGN_ LIST, and DELETE_LIST 


Method 
INSERT_LIST is used to form a temporary list that 
contains the linked data items of LIST1 and LIST2. 
ASSIGN _LIST assigns the temporary list to 
LIST3. DELETE_LIST deletes the temporary list. 





Figure 2.22A. Description of the CATENATE subroutine for 
catenating two lists and assigning the result to 
a third list 


CATENATE: 
PROCEDURE(LIST1, LIST2, LIST3); 

DECLARE 
(LISTL, LIST2, LIST3, T) POINTERS 
T = NULLS 
CALL INSERTLLIST(T, le LIST2)$ 
CALL INSERT_LLIST(T, le LISTIDS 
CALL ASSIGN_LIST(LISTS, Ts 
CALL DELETE_CIST(T)$ 

END 
CATENATES 


Figure 2.22B. Catenating two lists and assigning the result to a 


third list 
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1 
L2: 
L3: 
L4 
Subroutine 
Reference 
CATENATE(L1,L2,L3) L1: 
L2: 
L3: 
CATENATE(L2,L1,L3) L1: 
L2: 
L3: 
CATENATE (L4,L2,L4) L2: 









CATENATE (L2,L3,L3) 


Data List 
(before reference) 
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Figure 2.22C. Examples of references to the CATENATE subroutine 
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Searching Data Lists for Sublists 


Retrieval of information from a list may involve a pattern 
search through the list, such as scanning for a repeating 
decimal. The following discussion develops the 

FIND_ LIST function procedure, which searches a list for 
the appearance of another list. The search can be restricted 
to a portion of the list and need not involve the entire list. 


FIND _LIST Function Figures 2.23A, 2.23B, and 2.23C 
present the FIND LIST function procedure, which 
searches a list between two positions in the list for the first 
appearance of another list. The function uses four argu- 
ments: the list to be searched, the limiting positions of the 
search, and the list to be searched for. 

When the search is successful, FIND LIST returns the 
first position where the matching list appears. The func- 
tion returns a zero value when the search is unsuccessful. 


Testing Data Lists for Equality 


Two data lists may be tested for equality. The following 
discussion develops the EQUAL function procedure, which 
determines whether two lists contain the same data items 
arranged in the same order. 


EQUAL Function Figures 2.24A, 2.24B, and 2.24C pres- 
ent the EQUAL function procedure, which tests two lists 
for equality both in number and order of data items. The 
function returns a one-bit when the lists are equal and a 
zero-bit when they are not equal. 





FIND LIST Function 


Purpose 
To search a list between two data positions for the 
first appearance of a second list 


Reference 
FIND _LIST(LIST1, N1, N2, LIST2) 


Entry-Name Declaration 
DECLARE FIND_LIST 
ENTRY(POINTER, FIXED DECIMAL(5), 
FIXED DECIMAL(5), POINTER); 


Meaning of Arguments 
LIST1  --the list to be searched 
N1 --the position in LIST 1 where searching 
begins 
N2 --the position in LIST 1 where searching ends 
LIST2  --the list to be searched for 


Remarks 
The function returns the first position between N1 
and N2 where LIST2 appears in LIST1. If LIST2 is 
not found, the function returns a zero value. A zero 
value is also returned when LIST1 or LIST2 is null 
or N1 is greater than N2. 


Other Programmer-Defined Procedures Required 
GET_ND and SIZE 


Method 


GET_ND obtains data items from each list for 
comparison. 


Figure 2.23A. Description of the FIND LIST function for 
finding a list in another list | 
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FINO_LLIST?: 


DECLARE | 


PROCEDURE(LIST1» Nl» N2»y LIST2) 
RETURNS (FIXED DECIMAL(5))3 


(LISTL, LIST2) POINTER, 
(NL yN2gLL UL eSl,S2e TJ) 
FIXED DECIMAL(5)% 
/*@ IF LISTL OR LIST2 ITS NULL, 
RETURN ZERO. */ 
TF 
(LISTL = NULLIFC(LIST2 = NULL) 
THEN | 
RETURN(0)$ | 
/* IF LIST1 IS SHORTER THAN LIST2, 
RETURN ZERO. */ | 
S1 = SIZEC(LISTL)S 
S2 = SIZE(LIST2)$ 
IF 
$1<S2 
THEN 
RETURN(0O)$ 
/* INITIALIZE LOWER AND UPPER 
SEARCH LIMITS. */ 
LLE = NI3 UL = N23 
/* IF LOWER SEARCH LIMIT EXCEEDS 
SEARCH LIMIT, RETURN ZERO. */ 
IF | 
LLOUL 
THEN 
RETURN(0) 3 | 
/* IF LOWER SEARCH LIMIT EXCEEDS 
STZE OF LIST1, RETURN ZERO. */ 
IF 
LL>S1 
THEN 
RETURN(0)3 
/* IF LOWER SEARCH LIMIT IS LESS 
THAN ONE, ADJUST LIMIT. */ 


Figure 2.23B. Finding a list in another list 


Figure 2.23C. Examples of references to the FIND_ LIST function 
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Data List 


[Pel PEL Pe Yt POL PIZIN 


PEL ReRLRCLRBLRELRER 


ChEN 


IF 
LL<1 
THEN | 
LL = 13 
/* IF UPPER SEARCH LIMIT EXCEEDS 
SIZE OF LIST1, ADJUST LIMIT. ¥/ 
IF 
| UL>S1 
THEN 
UL = S13 a 
/* TF SIZE OF LIST2 EXCEEDS EXTENT 
OF SEARCHs, RETURN ZERO. */ 
IF 
S2>(UL ~ LL + 1) 
THEN 
RETURN(0)3 
/* FIND FIRST POSITION OF LIST2 
BETWEEN LOWER AND UPPER SEARCH 
LIMITS OF LIST1.#/ 


00 
I= tt TO (UL — S2 # 1)3 
00 
J = 1 TO S23 
IF 
GETLND(LIST1, I + J - 1)-2GET_NO 
(LIST2,J) 
THEN 
GO TO 
L3 
END; 
4/* LIST2 FOUND AT I=TH POSITION OF 
LISTL. */ 
RETURN(I)3 
Ls 
END; 
4/* LIST2 NOT FOUND. #/ 
RETURN(0) 3 
END 





FINOLLIST3 


Function Function 
Reference Value 


FIND_LIST(L1,1,7,L2) 
FIND _LIST(L3,3,6,L4) 
FIND_LIST(L5,2,4,L6) 
FIND_LIST(L7,1,3,L8) 


FIND_LIST(L8,1,4,L7) 


. 
3 
0 


EQUAL Function 


Purpose 
To test two data lists for equality 


Reference 
EQUAL(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE EQUAL ENTRY(POINTER, POINTER) 
RETURNS (BIT(1)); 


Meaning of Arguments 
LIST1 = --the first list 
LIST2  --the second list 


Remarks 
The function returns a one-bit when the lists are 
equal; otherwise, a zero-bit. If both lists are null, 
they are considered to be equal. 


Other Programmer-Defined Procedures Required 
ADDRESS_ NEXT and GET_DATA 


Method 


ADDRESS_ NEXT obtains successive list components. 


GET_DATA obtains the data element of each list 
component. Testing stops when corresponding list 
positions do not contain equal data items. Lists with 
different sizes are always unequal. 


Figure 2.24A. Description of the EQUAL function for testing 
the equality of two data lists 
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EQUAL 3 
PROCEDURE (LISTI, CIST2Z) 
RETURNS (BITC1LIDS 
DECLARE 
(LISTLZLIST2,ADORESS1,ADORESS2) 
POINTERS 
ADDRESS! = LIST13 
ADORESS2 = LIST2; 
L: 
IF 
ADDRESS1 = AODRESS2 


RETURN(°1°B)5 
IF 
(ADORESS1 = NULLITCADORESS2 = NULL) 


RETURN(°0°B)5 
IF 
GET_DATA(ADORESS1)~*GET_DATA 
(ADDRESS2) 
THEN 
RETURN(°O°B)$ 
ADDRESS1 = ADORESS_NEXT(ADDORESS1I)$ 
ADORESS2 = ADORESS_NEXT (ADORESS2) 3 
GO TO 
Ls 
END 
EQUAL $ 


Figure 2.24B. Testing two data lists for equality 







Function 
Reference 


Function 
Value 
EQUAL(L1,L2) 


— i 
— | 


EQUAL(L7,L8) ‘O’B 











Figure 2.24C, Examples of references to the EQUAL function 
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Comparing Data Lists 


The conventional string comparisons (less than, equal to, 
and greater than) may also be applied to data lists. The 
following discussion develops the COMPARE function 
procedure for comparing two lists. 


COMPARE Function 


Purpose 
To determine whether a list is less than, equal to, or 
greater than another list 


Reference 
COMPARE(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE COMPARE ENTRY(POINTER, 
POINTER) 
RETURNS(BIT(2)); 


Meaning of Arguments 
LIST1 = --the first list 
LIST2  --the second list 


Remarks 
When LIST1 equals LIST2, the function returns 
‘11'B. 
When LIST 1 is less than LIST2, the function returns 
‘01'B. 
When LIST 1 is greater than LIST2, the function 
returns ‘10’B. 


Other Programmer-Defined Procedures Required 
ADDRESS_NEXT and GET_DATA 


Method 
ADDRESS_ NEXT obtains the address of successive 
list components. GET _DATA obtains the data 
element of each component. Comparison begins 
with the first data item in each list and matches 
successive items in corresponding positions. 
Comparison stops when the first unequal match 
occurs. If the end of one list is reached before 
inequality is established, the shorter list is 
considered to be less than the longer. Comparison 
of two null lists produces an equal match. 





Figure 2.25A. Description of the COMPARE function for 
comparing two data lists | 
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COMPARE: 
PROCEDURE (LIST1, LIST2) 
RETURNS (BIT (2913 

DECLARE 

(01,02) CHARACTER(1), 
(LIST1,LIST2,ADDRESS1,AD0RESS2) 
POINTERS 
ADDRESS] = LISTLS; 
ADDRESS2 = LIST23 


IF 
ADDRESS1 = ADORESS2 
THEN 
RETURN(°21°B)$ 
IF 
ADDRESS1 = NULL 
THEN : 
RETURN(*°01°B)$ 
IF 
ADDRESS2 = NULL 


RETURN(*10°B)3 
Dl = GET_DATACADDRESS1)$ 
D2 = GET_DATA(AODDRESS2) 3 


RETURNC°01°B)3 
IF 
01>02 
THEN 
RETURN(*°10°6)3 
ADORESS1 = ADORESS_NEXT (ADORESS1)3 
ADORESS2 = ADDRESS_NEXT (ADDRESS2)3 
GO TO 
L3 


COMPARE 3 


Figure 2.25B. Comparing two data lists 


COMPARE Function Figures 2.25A, 2.25B and 2.25C 
present the COMPARE function procedure, which deter- 
mines whether one list is less than, equal to, or greater 
than another list. The function returns a two-position bit 
string. Both positions contain one-bits when the lists are 
equal. A zero-bit in the left position indicates a less-than 
comparison, and a zero-bit in the right position indicates a 
greater-than comparison. 


Function 
Data List Reference Value 


Lt: 
[ aE RPELPBLRPEN 


es = Pez] POLIN 











Function 





COMPARE (L1,L2) 














COMPARE (L4,L3) ‘01'B 
(<) 
COMPARE (L3,L4) ‘10’B 
(>) 
COMPARE (L5,L6) ‘10'B 
(>) 
COMPARE (L7,L8) '11'B 


Figure 2.25C. Examples of references to the COMPARE function 


Reversing Data Lists 


Frequent manipulation of data items at the end of a list 
may become time-consuming, because the addresses of the 
items must be obtained by proceeding serially through the 
list. One way of improving the access time for data items 
at the end of a list is to reverse the order of the items in 
the list. The desired items will then lie at the front of the 
list, and fewer items will have to be passed over. 

The following discussion develops the REVERSE sub- 
routine procedure for reversing the order of the data items 
in a list. 


REVERSE Subroutine Figures 2.26A, 2.26B, and 2.26C 
present the REVERSE subroutine procedure, which re- 
verses the order of the data items in a list. The procedure 


removes successive data items from the front of the list 
and inserts them successively at the front of a temporary 
list. When the original list becomes null, it receives the 
items in the temporary list. 


Sorting Data Lists 


The following discussion develops the SORT subroutine 
for arranging the data items of a list in ascending sequence. 


SORT Subroutine Figures 2.27A, 2.27B, and 2.27C pres- 
ent the SORT subroutine procedure. The procedure re- 
moves all items from the list and inserts them in a tempo- 
rary list. Each item is then reinserted into the original list 
in sort sequence. 
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REVERSE Subroutine 


Purpose 
To reverse the order of the data items in a list 


Reference 
REVERSE(LIST) 


Entry-Name Declaration 
DECLARE REVERSE ENTRY(POINTER); 


Meaning of Argument 
LIST — --the list to be reversed 


Remarks 
LIST can be null. 


Other Programmer-Defined Procedures Required | 
INSERT_FD and REMOVE_FD 


Method | 
REMOVE_FD obtains and removes successive data 
items from the first position of LIST. INSERT_FD 
stores each item (as it is obtained) in the first 
position of a temporary list, T. The following 
reference is used: | 


INSERT _FD(T, REMOVE_FD(LIST)) 
When LIST becomes null, it is assigned the value of 


pointer T. Then DELETE_LD(LIST) removes 
whatever was in the data item in AVAIL. 


Figure 2.26A. Description of the REVERSE subroutine for 
reversing a data list 
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Data List Subroutine Data List 
(before reference) _ Reference » (after reference) 


REVERSE (L1) 


REVERSE (L2) — 


REVERSE: PROCEDURE(LIST)3 
DECLARE (LIST, T) POINTER, 
AVAIL EXTERNAL POINTERS 
T = AVAIL3 
AVAIL->POINTER = NULL? 
DO WHILE (LIST w= NULLD3 
CALL INSERT_FDO(T,REMOVE_FDULIST))3 
END} 
LIST = T3 
CALL DELETE_LO(LIST)3 
ENO REVERSE} 


Figure 2.26B. Reversing a data list 


wu ChE bELPEN 
L2: 


Figure 2.26C. Examples of references to the REVERSE subroutine 
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SORT3 . 
: PROCEDURE (LIST)3 
SORT Subroutine BECLARE 
(LISTe Ty ADORESS) POINTER, 


D CHARACTER(1)> 


Purpose . Oo N FIXED DECIMAL (5)3 
To arrange the data items in a list into ascending IF 
sequence LIST = NULL 
THEN 
RETURN3 
Reference T = LIST; 
SORT(LIST) LIST = NULL3 
00 
: WHILE (T-2#NULL)3 
Entry-Name Declaration D = REMOVE_FD(T)3 
DECLARE SORT ENTRY(POINTER); N = 03 
ADDRESS = LIST$ 
; dO 
Meaning of Argument WHILE (ADDRESS7=NULL 3 
LIST --the list to be sorted N=N #13 
IF 
GET_DATA( ADDRESS) >= D 
Remarks | THEN 
LIST can be null. 00; 
CALL INSERT_ND(LISToNoD)3 
Go TO 
Other Programmer-Defined Procedures Required L3 
REMOVE_FD,GET_DATA, ADDRESS_NEXT, ENO; 
CALL INSERT_LD(LIST,D)3 
Method 2 
All data items are removed from LIST and assigned ad 
to a temporary list, T. Each item is then reinserted SORT; 


into LIST in ascending sequence. 
Figure 2.27B. Sorting a data list 


Figure 2.27A. Description of the SORT subroutine for sorting 
a data list 


Data List Subroutine Data List 
(before reference) Reference (after reference) 


ur: [ bole. bony boo SORT(L1) : [| bop peel binX 
2 TS SORT(L2) 





Figure 2.27C. Examples of references to the SORT subroutine 
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Converting Character Strings to and from Data Lists 


The similarities between character strings and data lists (as 
developed in this chapter) permit the conversion of char- 
acter strings to and from data lists. The following discus- 
sions develop two subroutine procedures for such 
_conversions: 
1. STRING_TO_LIST, which converts a character 
string to a data list 
2. LIST_TO_ STRING, which converts a data list to a 
character string 


STRING_TO_LIST Subroutine Figures 2.28A, 2.28B, 
and 2.28C present the STRING _TO_LIST subroutine 
procedure, which obtains successive characters from the 
character string and inserts them into the data list. The 
character string is not changed by the procedure. 


LIST_TO_STRING Subroutine Figures 2,29A, 2.29B, 
and 2.29C present the LIST_TO STRING subroutine 
procedure, which obtains successive items from the list and 
inserts them into the string. The data list remains un- 
changed. 


Manipulating Lists Recursively 


The structure of a simple data list always satisfies one of 
these conditions: | 

1. The data list is null. 

2. The data list contains one data item. 

3. Each data item in the list is followed by a data list 
(which may be null). | 


These conditions provide an elementary example of 
recursive organization (see Figure 2.30). Insertion of a data 
item into a data list does not change the organization of 
the list; although the size of the list increases, it still retains 
the structure of a list. Similarly, deletion of a data item 
from a data list also results in a list organization. 
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STRING_TO_LIST Subroutine 


Purpose 
To convert a character string to a data list 


Reference 
STRING_TO_LIST(STRING, LIST) 


Entry-Name Declaration 
DECLARE STRING_TO_LIST 
ENTRY(CHARACTER(*), POINTER); 


Meaning of Arguments 
STRING _ --the character string to be converted to a 
data list 
LIST --the list to which the converted 
character string is to be assigned 


Remarks 
STRING is a fixed-length character string that can be 
of any storage class. If STRING has a zero length, 
LIST becomes null. In all cases, STRING remains 
unchanged. 


Other Programmer-Defined Procedures Required 
DELETE_LIST and INSERT_LD 


Method 
DELETE_LIST deletes LIST before conversion 
begins. The built-in function SUBSTR obtains 
successive characters from STRING. INSERT_LD 
inserts successive characters at the end of LIST. 





Figure 2.28A. Description of the STRING TO_LIST 
subroutine for converting a character string 
to a data list 


STRING_TO_LLISTs 
PROCEDURE (STRING,LIST)$ 
DECLARE 
LIST POINTER, 
STRING CHARACTER(*), 
I FIXED DECIMAL(5); 
CALL DELETE_LIST(LIST)$ 


00 
I = 1 TO LENGTH(STRING) $ 
CALL INSERT_LO(LIST,SUBSTR 
(STRING, I o1))3 
END$ 
END 


STRING_TO_LLIST$ 


Figure 2.28B. Converting a character string to a data list 












Data List 
(before reference) 


SE ee GN 


L2: 


Subroutine Data List 
Reference (after reference) 


au: LPL PL Piel PON 
[ Pell PEEK 











STRING TO_LIST(‘ABCD’,L1) 





STRING_TO_LIST(‘4F’,L2) 





Figure 2.28C. Examples of references to the STRING_TO_LIST subroutine 
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LIST _TO_STRING Subroutine 


Purpose 
To convert a data list to a character string 


Reference 
LIST_TO_STRING(LIST, STRING) 


Entry-Name Declaration 
DECLARE LIST_TO_STRING 
ENTRY(POINTER, CHARACTER("*)); 


Meaning of Arguments 
LIST --the list to be converted to a character 
string 
STRING _ --the character-string variable to which 
the converted list is to be assigned 


Remarks 
STRING is a fixed-length character string that can be 
of any storage class, but storage must have been 
allocated for it before LIST _TO_STRING is 
invoked. When the length of STRING is less than 
the size of LIST, excess data items in LIST are not 
inserted into STRING. When the length of STRING 
is greater than the size of LIST, excess positions in 
STRING become blank. When LIST is null, all 
positions in STRING become blank. In all cases, 
LIST remains unchanged. 


Other Programmer-Defined Procedures Required 
GET_ND 


Method 
GET _ND obtains successive data items from LIST. 
The first data item is assigned to STRING. 
Remaining data items are inserted into successive 
positions of STRING through the pseudo variable 
SUBSTR. 





Figure 2.29A. Description of the LIST_TO STRING subroutine 
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LIST_TO_LSTRING: 
PROCEDURE (LIST, STRING) 
DECLARE 
LIST POINTER, 
STRING CHARACTER(*), 
I FIXED DECIMAL(5)$ 
STRING = GET_ND(LIST,1)3 


00 
| I = 2 TO LENGTH(STRING)$ 
SUBSTRISTRINGs Tol) = GET_LNDILIST,I)$ 
END; 
ENO 


LIST_TOLSTRINGS 


Figure 2.29B. Converting a data list to a character string 


Data List and Character String 
(before reference) 
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Subroutine 
Reference 


String 
(after reference) 


LIST TO STRING(L1,S1) 


LIST_TO_STRING(L2,S2) 


LIST_TO_STRING(L3,S3) 


Figure 2.29C. Examples of references to the LIST TO STRING subroutine 


List with Three Items 





Figure 2.30. Recursive structure of a data list 


A PL/I procedure may be declared to have the RECUR- 
SIVE option. An active recursive procedure can be acti- 
vated from within itself. This successive invocation of itself 
continues until terminated by itself. 

The recursive facilities of PL/I procedures allow list- 
processing operations to be performed recursively. This 
section develops six recursive procedures for the following 
operations: 

. Recursive deletion of data lists 

. Recursive computation of data list sizes 

. Recursive searching for data items in data lists 
. Recursive linking of data lists 

. Recursive testing for equality of data lists 

. Recursive comparison of data lists 


NM BR WN & 


Note that earlier discussions developed nonrecursive (that 
is, iterative) procedures for each of these operations. The 
relative merits of recursive methods compared to iterative 
techniques is a controversial aspect of computer program- 
ming. Generally, recursive methods produce more compact 
program statements at the expense of increased execution 
time and storage space. This expense may be justified, 
however, when iterative techniques distort the natural 
organization of a recursive application and produce pro- 
gramming complexities that can be avoided with recursive 
methods. 

Appendix 1 contains a summary of the recursive facili- 
ties for PL/I procedures. 


Recursive Deletion of Data Lists 


Figures 2.30A through 2.30D present the DELETER sub- 
routine procedure, which deletes a data list recursively. 
The procedure performs three basic operation: 

1. Tests whether the list is null 

2. Deletes the first data item in the list 

3. Invokes itself recursively 


Each recursive invocation of DELETER deletes a data item 
from the list. When the list becomes null, control returns 
to each higher level invocation until the original point of 
invocation is reached. 

Figure 2.30C illustrates successive stages in the recursive 
deletion of a data list. 
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DELETER Subroutine 


Purpose 
To delete a data list 


Reference 
DELETER(LIST) 


Entry-Name Declaration 
DECLARE DELETER ENTRY(POINTER); 


Meaning of Argument 
LIST _ --the list to be deleted 


Remarks 
LIST is null after deletion. 


| Other Programmer-Defined Procedures Required 
DELETE FD 


Method 
DELETER is a recursive subroutine. Each 
invocation (initial and recursive) causes 
DELETE_FD to delete the first data item from 
LIST. When LIST becomes null, recursion stops, 
and control returns to the initial point of 
invocation. 





Figure 2.30A. Description of the DELETER subroutine for 
recursive deletion of a data list 


OELETER: , 
PROCEDURE(LIST) RECURSIVE 
DECLARE : 
LIST POINTERS 
IF 


LIST = NULL 
THEN 
RETURNS 
CALL DELETE_FD(LIST)3 
CALL DELETER(LIST)$ 


DELETER; 


Figure 2.30B. A recursive subroutine for deleting a data list 
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LIST: 


Figure 2.30C. Successive stages in the recursive deletion of a data 
list 





Figure 2.30D shows the flow of control through recur- 
sive invocations of the DELETER subroutine. To simplify 
the presentation, the diagram duplicates the subroutine at 
each stage of recursion. It also shows the state of the list 
each time control enters the subroutine. 

The diagram begins at the top of Figure 2.30D with 
execution of the statement: 


CALL DELETER (LIST); 


LIST contains two data items, A and B, whose list com- 
ponents are assumed to be at locations 10 and 75. Since 
LIST is not null the first time control enters DELETER, 
item A is deleted by the subroutine DELETE FD, and 
DELETER is invoked a second time with LIST as the 
argument. Again, LIST is not null, and item B is deleted by 
DELETE FD. When DELETER is invoked for the third 
time, LIST is null, and no further invocations are required. 

The RETURN statement in the third copy of DE- 
LETER returns control to the END statement in the sec- 
ond copy of DELETER. This END statement then returns 
control to the END statement in the first copy of DE- 
LETER. Finally, control returns to the statement that 
follows the original invocation of DELETER. 

In the diagram, solid lines denote flow of control from 
an invoking reference to the invoked procedure, and 
beaded lines represent flow of control from the invoked 
procedure back to the statement that follows the invoking 
reference. 


CALL DELETER(LIST): 10 | BN 


NEXT STATEMENT:...; 





DELETER: 
PROCEDURE(LIST) RECURSIVE; 
DECLARE LIST POINTER; 


IF LIST=NULL THEN RETURN; 


CALL DELETE_FD(LIST); 


LIST: oN 


CALL DELETER(LIST); 


END DELETER; 








DELETER: 


PROCEDURE (LIST) RECURSIVE; 









DECLARE LIST POINTER; 






IF LIST=-NULL THEN RETURN; 






CALL DELETE _FD(LIST); 





ust; [\] 


CALL DELETER(LIST); 






» END DELETER; 


DELETER: 
PROCEDURE(LIST) RECURSIVE; 


DECLARE LIST POINTER; 


IF LIST=-NULL THEN RETURN; 
CALL DELETE _FD(LIST); 
CALL DELETER(LIST); 


END DELETER; 


Figure 2.30D. Deleting a list recursively 


Recursive Computation of Data List Sizes 


Figures 2.31A through 2.31D present the SIZER function, 
which computes the size of a data list recursively. When 
the list is null, SIZER returns a zero value. If the list is not 
null, the procedure returns the value of the expression: 


1 + SIZER(ADDRESS_NEXT(LIST)) 
Evaluation of this expression requires recursive invocation 


of SIZER. The addresses of successive data items in the list 
serve as the arguments of successive invocations of SIZER. 


SIZER Function 


Purpose 
To obtain the size of a data list 


Reference 
SIZER(LIST) 


Entry-Name Declaration 
DECLARE SIZER ENTRY(POINTER) 
RETURNS(FIXED DECIMAL(5)); 


Meaning of Argument 
LIST _--the list whose size is to be computed 


Remarks 


The maximum possible size is 99999. If LIST is 
null, the function returns a zero size. 


Other Programmer-Defined Procedures Required 
ADDRESS_NEXT 


Method 
SIZER is a recursive function. Each invocation 
(initial or recursive) causes the value of the 
following expression to be returned: 


1+SIZER(ADDRESS_NEXT(LIST)) 
When the argument becomes null, recursion stops, 


and control returns to the initial point of 
invocation. 





Figure 2.31A. Description of the SIZER function for 
recursive computation of the size of a data list 
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SIZERSPROCEDURE (LIST) RETURNS 

(FIXED DECIMAL(5)) RECURSIVES 
DECLARE 

LIST POINTER; 

IF LIST = NULL THEN RETURN (0)3 

RETURN | 

(1 # SIZER (ADORESS_NEXT(LISTIIDS 
END SIZER$ | 


_ Figure 2.31B. A recursive function for obtaining the size of a data 


list 


The above expression becomes equivalent to an arith- 
metic series of ones, which is terminated by the zero value 
that is returned when the end of the list is reached. The 
number of ones in the equivalent series equals the number 
of data items in the list. Figure 2.31C illustrates the succes- 
sive stages performed by SIZER for a data list of three 
items. 

Figure 2.31D shows how program control flows 
through recursive invocations of SIZER. The diagram 
duplicates SIZER at each stage of recursion. It also shows 
the argument value passed by each invocation, the flow of 
control into and out of the function, and the value re- 
turned to each invoking reference. Since pointer parameter 
LIST has the automatic storage class, storage is auto- 
matically allocated for parameter LIST at each level of 
recursion, and the address of the next component in the 
list is assigned as the value of the new generation of para- 
meter LIST. Solid lines in the diagram denote flow of 
control from an invoking reference to the invoked pro- 
cedure. 

The diagram begins with the execution of the assign- 
ment statement: 


LENGTH = SIZER(LIST); 


As illustrated, LIST is the head pointer of a two- 
component data list whose components have been given 
the arbitrary addresses 100 and 250. For a value to be 
assigned to variable LENGTH on the left of the above 
assignment statement, the expression on the right must be 
evaluated first. This expression consists of a reference to 
the SIZER function. 

The head pointer LIST serves as the assignment of the 
reference and has an address value of 100, which is passed 
to SIZER. When control enters the function, storage is 
allocated for parameter LIST, which is internal to the 
procedure, and the value 100 is assigned to this storage. 
Because parameter LIST is not null, the following state 
ment is executed: 


RETURN (1 + SIZER (ADDRESS_ NEXT (LIST))); 
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Figure 2.31C. Successive stages in the recursive computation of the size of a data list 


This statement cannot return control until its expression is 
evaluated. However, the expression itself contains refer- 
ence to SIZER that causes recursive invocation of the 
function with an argument value of 250. The value 250 is 
obtained from the reference ADDRESS_ NEXT (LIST). 
This second invocation of SIZER, which is represented 
by the second copy of the function in Figure 2.31D, 
causes new storage to be allocated for parameter LIST 
with the address value of 250. Again, parameter LIST does 
not have a null value; therefore, the RETURN statement 
mentioned above is reexecuted in the second copy of the 
function. Once more, return of control is suspended until 


the expression within the RETURN statement is evaluated. 


The evaluation causes a third invocation of SIZER with a 
null argument value. 

When control enters the function for the third time 
(represented by the third copy of SIZER in Figure 2.31D), 
new storage is allocated for parameter LIST, to which a 
null value is assigned. At this stage of recursion, the null 
value of parameter LIST causes the statement: 


RETURN (1 + SIZER (ADDRESS_NEXT))); 


In this statement, SIZER has a value of zero, and the value 
returned by the statement, therefore, is one (1 = 1 + 0). 
This value is returned to the still previous point of invoca- 
tion, which occurred within the first copy of the function 
and is also associated with the statement: 


RETURN (1 + SIZER (ADDRESS_ NEXT (LIST))); 


This time SIZER has a value of one, and the statement 
returns a value of two (2 = 1 + 1) to the previous point of 
invocation, which occurred on the right side of the assign- 
ment statement: 


LENGTH = SIZER (LIST); 


At this point, the value of two for the function reference is 
assigned to variable LENGTH. 

Throughout the entire evaluation, the data list remains 
unchanged. Each recursive allocation of parameter LIST 
serves as a temporary head pointer for the list and leaves 
the original head pointer undisturbed. 
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argument 
passed: 
100 


LENGTH = 


PROCEDURE(LIST) RETURNS(FIXED DECIMAL(5)) 
RECURSIVE; 
DECLARE LIST POINTER; 
IF LIST=NULL THEN RETURN(O); 


value 


returned: 
2 


RETURN(1 + SIZER(ADDRESS_NEXT(LIST))); argument 


passed: 
250 





END SIZER; 


SIZER: 
PROCEDURE(LIST) RETURNS(FIXED DECIMAL (5)) 
RECURSIVE; 


DECLARE LIST POINTER; 
IF LIST=NULL THEN RETURN(O); 


value 









returned: 
1 


RETURN(1 + SIZER(ADDRESS_NEXTI(LIST))); 





argument 
Passed: 


NULL 









END SIZER; 


SIZER: 


PROCEDURE(LIST) RETURNS(FIXED DECIMAL (5)) 
RECURSIVE; | 
DECLARE LIST POINTER; 

IF LIST=-NULL THEN RETURN(O); 


value 


returned: 
0 






IF LIST=NULL THEN RETURN (0); 
RETURN(1 +SIZER(ADDRESS_NEXT(LIST))); 
END SIZER; 


Figure 2.31D. Computing the size of a data list recursively 


FINDR Function 


Purpose 
To find the position of the first occurrence of a data 
item in a data list 


Reference 
FINDR(LIST, D) 


Entry-Name Declaration 
DECLARE FINDR ENTRY(POINTER, 
CHARACTER(1)) 
RETURNS(FIXED DECIMAL(5)); 


Meaning of Arguments 
LIST --the list to be searched 
D --the data item to be found 


Remarks 
The function returns a zero value when LIST does 
not contain D. 


Other Programmer-Defined Procedures Required 
GET_FD and ADDRESS_NEXT 


Method 
FINDR is a recursive function. A null list argument 
causes a zero value to be returned. When D equals 
GET_FD(LIST), the value one is returned; 
otherwise, the value of the following expression is 
computed: 


1+ FINDR(ADDRESS_NEXT(LIST), D) 


This expression produces recursive invocation of 
FINDR while the tist argument is not null. The 
value of the expression is assigned to variable N, 
which specifies the position of D in the list. When 
D is not in the list, the value of N equals the size 
of the list and must be set to zero before FINDR 
is terminated. Multiplication of N by variable T, 
which equals one when D is in the list, assures 
proper control over the value of N. Declaring N 
and T to be static variables causes all levels of 
recursion to deal with the same storage for the 
variable. 


Figure 2.32A. Description of the FINDR function for 
recursive searching of a data list 


FINOR: 
PROCEDURE (LIST, 0) RETURNS 
(FIXED DECIMAL(5)) RECURSIVE; 
DECLARE 
LIST POINTER,: 
D CHARACTER(1)> 
(TON) FIXED DECIMAL(5) STATIC; 


TaN = 13 
IF 
LIST = NULL 
THEN 
DO; 
T = O$ RETURN(O)$ 
END; 


IF 
D~=GET_FO(LIST) 
THEN 
N = 1 + FINDRCADDRESS_NEXT 
(LIST),D0);$ 
RETURN(T#N) 5 
END 
FINDRs 


Figure 2.32B. A recursive function for finding the position of a 
data item in a data list 


Recursive Searching for Data Items in Data Lists 


Figures 2.32A and 2.32B present the FINDR function 
procedure, which performs a recursive search for the first 
occurrence of a data item in a data list. When the data item 
is found, the function returns its position in the list. Ab- 
sence of the item in the list is indicated by a zero value. 

FINDR computes the position of the data item by 
performing a recursive count similar to the size calculation 
of SIZER (Figures 2.31A, 2.31B, and 2.31C). When the 
data item is not in the list, the position count is changed to 
zero by a zero multiplication factor. 


Recursive Linking of Data Lists 


Figures 2.33A and 2.33B present the LINKR subroutine 
procedure, which links two data lists recursively. Each 
invocation of the subroutine causes the data item at the 
front of one list to be removed and to be inserted at the 
end of a second list. When the first list becomes null, recur- 
sion stops. 
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LINKR Subroutine 


Purpose 
To link two data lists 


Reference 
LINKR(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE LINKR ENTRY(POINTER, POINTER); 


Meaning of Arguments 
LIST1 = --the list to which the second list is to be 
linked 
LIST2  --the second list 


Remarks 
LIST2 is null after its data items are linked to LIST 1. 


Other Programmer-Defined Procedures Required 
REMOVE_FD and INSERT_LD 


Method 
LINKR is a recursive subroutine. Each invocation 
(initial or recursive) removes the first data item from 
LIST2 and inserts the data item at the end of 
LIST1. When LIST2 becomes null, recursion stops, — 
and control returns to the initial point of invocation. 





Figure 2.33A. Description of the LINKR subroutine for 
recursive linking of two data lists 


LINKRs | 
PROCEDURE (LISTIL,LIST2) RECURSIVES 
DECLARE 
(LISTI»LIST2) POINTERS 
IF 


LIST2 = NULL 
THEN 

RETURNS 
CALL INSERT_LO(LIST1,REMOVE_FD 
(LIST2))$ 
CALL LINKR(LISTI,LIST2)3 | 

END 
LINKR; 


Figure 2.33B. A recursive subroutine for linking two data lists 
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Recursive Testing for Equality of Data Lists 


Figures 2.34A and 2.34B present the EQUALR function 
procedure, which performs a recursive test for equality of 
two data lists. Recursion occurs when data items in cor- 
responding list positions are equal. | 

The function returns a one-bit when the lists are equal 
and a zero-bit when they are not equal. 


EQUALR Function 


Purpose 
To test two data lists for equality 


Reference 
EQUALR(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE EQUALR ENTRY(POINTER, 
POINTER) 
RETURNS(BIT(1)); 


Meaning of Arguments 


LIST1 = --the first list 
LIST2 _ --the second list 


Remarks | 
The function returns a one-bit when the lists are 
equal; otherwise, it returns a zero-bit. Null lists 
are considered equal. 


Other Programmer-Defined Procedures Required 
ADDRESS_NEXT 


Method : | 
EQUALR is a recursive function. When the data 
items in the first position of each list are not 
equal, the function returns ‘O’B; otherwise, it 
returns the value of the following expression: 


EQUALR(ADDRESS_NEXT(LIST1), 
ADDRESS_NEXT(LIST2)) 


This expression causes recursive invocation of 
EQUALAR as long as corresponding data items 
are equal. When one (but not both) of the 
arguments becomes null, recursion stops, and 
the function returns ‘0’B. When both _ 
arguments become null together, recursion 
stops, and the function returns ‘1’B. 





Figure 2.34A. Description of the EQUALR function for 
recursively testing the equality of two data 
lists : - 


EQUALR: 
PROCEDURE (LIST1l, LIST2) RETURNS 


(BIT(L)) RECURSIVES 
DECLARE 
(LISTL,LIST2) POINTERS 
IF 
LIST1L = LIST2 
THEN 
RETURN(*1°BD3$ 
IF 
LIST1L = NULL 
THEN 
RETURN(*0O"B)3 
IF 
LIST2 = NULL 
THEN 
RETURN(*'O*B)$ 


IF 
GET_FO(LIST1I~#GET_FO(LIST2) 
THEN 
RETURN(*0"B)3 
RETURN (EQUALR(CADDRESS_NEXT(LISTI)» 
ADDRESS_NEXTILIST2)993 
END 
EQUALR S$ 


Figure 2.34B. A recursive function for testing the equality of two 
data lists 


Recursive Comparison of Data Lists 


Figures 2.35A and 2.35B present the COMPARER func- 
tion procedure, which performs a recursive comparison of 
two data lists to determine whether one is less than, equal 
to, or greater than the other. Recursion occurs while data 
items in corresponding list positions are equal. 

For equal lists the function returns the value ‘11’B. 
When the first list is less than the second, the function 
returns ‘01’B. When the first list is greater than the second, 
the returned value is “10°B. 


COMPARER Function 


Purpose 
To determine whether a list is less than, equal to, 
or greater than another list 


Reference 
COMPARER(LIST1, LIST2) 


Entry-Name Declaration 
DECLARE COMPARER ENTRY (POINTER, 
POINTER) 
RETURNS(BIT(2)); 


Meaning of Arguments 
LIST1 = --the first list 
LIST2 = --the second list 


Remarks 
When LIST1 equals LIST2, the function returns 
‘11'B. 
When LIST1 is less than LIST2, the function 
returns ‘O1'B. 
When LIST1 is greater than LIST2, the function 
returns ‘10’B’ 


Other Programmer-Defined Procedures Required 
GET FD and ADDRESS_NEXT 


Method 
COMPARER is a recursive function. When the data 
item in the first position of LIST 1 is less than the 
data item in the first position of LIST2, the function 
returns ‘01’B. When it is greater, the function 
returns ‘10’B. When the data items are equal, the 
function returns the value of the following 
expression: 


COMPARER(ADDRESS_NEXT(LIST1), 
ADDRESS_NEXT(LIST2)) 


This expression causes recursive invocation of 
COMPARER as long as corresponding data items 
are equal. Recursion stops when one or both of the 
arguments becomes null. When both arguments 
become null together, the function returns ‘11’B. 
When only the first argument becomes null, the 
function returns ‘01’B. When only the second 
argument becomes null, the function returns 

‘10‘B. 





Figure 2.35A. Description of the COMPARER function for the 
recursive comparison of two data lists 
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COMPARER: 
PROCEDURE (LIST1, LIST2) RETURNS 
(BIT(2)) RECURSIVE; 
DECLARE 
(LISTL,»LIST2) POINTER, 
(01,02) CHARACTER(1)3 
IF 
LIST] = LIST2 
THEN 
RETURN(*11°B)5 
IF 
LIST] = NULL 
THEN 
RETURN('01'B)$ 
IF 
LIST2 = NULL 
THEN 
RETURN(*10°B)5 
Ol = GET_FO(LIST1)$ 
D2 = GET_FD(LIST2)3 


IF 


RETURN(*10°B)3 
RETURN(COMPARER(ADDRESS_NEXT(LIST1)¢ 
ADDRESS_NEXT(LIST2)))3 

ENO 
COMPARERS 


Figure 2.35B. A recursive function for comparing two data lists 


Using Simple Data Lists 


The similarities between the simple data lists of this 
chapter and character strings in general provide a variety of 
list-processing applications concerned with text editing, 
pattern searching, and symbol manipulation. The following 
discussions develop programs for eight applications in 
these areas: 

. Editing cash values 

. Removing edit symbols from cash values 

. Expanding a multiple assignment statement 

. Expanding a picture specification 

. Contracting a picture specification 

. Adding variable-length integers 

. Subtracting variable-length integers 

. Gathering DECLARE statements in a procedure 


CONN NBR WN = 


Each application uses the procedures developed earlier in 
this chapter, and, although list-processing techniques are 
not essential for these applications, they improve program- 
ming flexibility and provide greater control over storage 
than is available with more conventional programming 
methods. 
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Editing Cash Values 


Figures 2.36A and 2.36B present the $EDIT subroutine 
procedure, which accepts an unedited cash value in list 
form and inserts appropriate edit symbols into the list. 

The procedure assumes that the argument list contains 
no characters other than digits. The number of digits is 
arbitrary and is restricted only by the size of the list of 
available storage components, AVAIL. 


$SEDITs 

PROCEDURE (CASH) $ 
DECLARE 

CASH POINTER,» 

(OA, OB) CHARACTER(1) >» 

S FIXED DECIMAL(5)3$ 
ZEROS: 

00 
WHILE (CASH==NULL) 3 
IF 
GET_FO(CASH) ~= *'0O* 
THEN 
GO TO 

PERIOD; 

CALL DELETE_FD(CASH)$ 
END ZEROS; 
PERIOD: 

S = SIZE(CASH)$ 

IF S = O THEN DO$ 

CALL STRING _TO_LIST(*$0.00* »CASH) 3 


RETURN; 
END; 
IF S = 1 THEN DO; 
CALL STRING_TO_LIST(*$0.0*| |REMOVE_FD 
(CASH) »CASH)$ RETURNS 
END; 
IF S = 2 THEN 003 
DA = REMOVE_FD(CASH); 
OB = REMOVE_FD(CASH); 
CALL STRING_TO_LIST(*S$0.*]] DAI |]0B8,CASH)3 
RETURNS 
END3 
CALL INSERT_NO(CASH, S—1ly*.')3 
S$ = S-23 
COMMAS: 
S$ = S-33 
IF 
$>0 
THEN 
003 
CALL INSERT_ND(CASH,S41lo%e")3 
GO TO 
COMMAS$ 
ENO3 
$_SIGN3 
CALL INSERT_FO(CASH,"$!)3 
END | 


SEDIT3 


Figure 2.36A. Editing cash values 


Data List 
(before reference) 





U3: | Fe PAL RIN 
la: | -—*2] PHIIN 


Subroutine 
Reference 


$E DIT(L1) 


$EDIT(L2) 


$E DIT(L3) 


$E DIT(L4) 


$EDIT(L5) 


$EDIT(L6) 


6] Fo] 
a. we 


[Fas bel bl bel 





a} pes] Pe 
2{ ee] Pe 


: 


o[\ 


Figure 2.36B. Examples of references to the $EDIT subroutine 


$EDIT deletes leading zeros in the argument list and 
inserts a decimal point, commas, and a dollar sign, as shown 
in Figure 2.36B. Values less than a dollar always receive a 
zero before the decimal point. The size of the argument 
list can either decrease or increase, depending on the num- 
ber of leading zeros that are deleted and the number of 
edit symbols that are inserted. 

Although PL/I provides extensive editing facilities 
through the PICTURE attribute and the P format item for 
edit-directed input and output, these facilities may not be 


sufficient in particular applications. The $EDIT procedure 
shows how list-processing techniques may be used to con- 
struct editing procedures for special needs. 


Removing Edit Symbols from Cash Values 


Figures 2.37A and 2.37B present the DE EDIT subrou- 
tine procedure, which accepts an edited cash value in list 
form and removes the edit symbols from the list. This 
procedure may be considered to be the inverse of the 
$EDIT procedure (Figures 2.36A and 2.36B). 
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DE_EDIT: 
PROCEDURE (CASH) $ 
DECLARE 
CASH POINTER, 
C CHARACTER(1), 
I FIXED DECIMAL(5); 
DO 
I = 1 TO SIZE(CASH); 
C = REMOVE_FO(CASH) >; 
IF | 
Craze ¢ 


THEN 


Figure 2.37A. Removing edit symbols from cash values 


u OD) 
el 
i CR ol 
on 
ae 


Crz’ ge 
THEN 
IF 
C~= e 9 e 
THEN 
IF 
Caz?! 
THEN 
CALL INSERT_LO(CASH,C)3$ 
END; 
END 
DE_EDIT>; 
Data List 


(before reference) 


Bie 
2 
ee 
2] 
az 


2 Maaco ens es enieeesiemera mee Teer SO 


On, OS, oe, oe 
|. T Fela] ei N 

S$] Fes] Fe] bes] | 
| Pe] Pez Pes 


us: [_}-—o/s] Foe] bois] tet Peel PsA 


us | 8] mo] Feet Fee] PON 
: | fos] Feo] be] Feel PHN 


Subroutine Data List 
Reference (after reference) 


DE_EDIT(L1) 


DE_EDIT(L2) 


DE_EDITI(L3) 


DE_EDIT(L4) 
DE_EDITILS5) 


DE_EDIT(L6) 





Figure 2.37B. Examples of references to the DE_ EDIT subroutine 


Expanding a Multiple Assignment Statement 


Figures 2.38A and 2.38B present the A_ EXPAND subrou- 
tine procedure, which accepts a multiple assignment state- 
ment in list form and expands the list to a series of simple 
assignment statements. 

This procedure provides an elementary example of how 
list-processing techniques may be used to construct a PL/I 
compiler. Source statements can be treated as character 
strings, which are converted to list form and then analyzed 
by list-processing procedures. Using successive levels of 
analysis will eventually convert source statements to their 
equivalent object code. 


Expanding a Picture Specification 


Figures 2.39A and 2.39B present the P_ EXPAND subrou- 
tine procedure, which accepts a PICTURE specification in 
list form and expands the list so that it contains no repeti- 
tion factors. 

This procedure could be used in a PL/I compiler to 
convert source text to a standard internal format. It could 
also be used in a conversion program to alter source text so 
that it becomes acceptable to a restricted compiler that 
does not process all PL/I features, such as repetition 
factors. 


A_EXPAND: 
PROCEDURE (ASSIGNMENT) 3 
DECLARE 
N FIXED DECIMAL(5), 
(ASSIGNMENT, RIGHT_HALF) POINTERS 
4* INITIALIZE. */ 
RIGHT_HALF = NULLS 
/* FIND POSITION OF EQUAL SIGN IN 
ASSIGNMENT LIST. #/ 
00 
N = 1 TO SIZECASSIGNMENT) BY 135 
IF 
(GET_NOCASSIGNMENT, NDD= (*%&=* 2 
THEN 
GO TO 
BREAKS; 
END; 
PUT SKIP LIST(C®*NO EQUAL SIGN®*)$ 
GO TO OVER; 
7* SPLIT RIGHT HALF FROM ASSIGNMENT 
LIST ANO INSERT IN RIGHT_HALF 
LIST. */ 
BREAK: 
CALL SPLITCASSIGNMENT ANeRIGHT_HALF)$ 
/* REPLACE EACH COMMA IN ASSIGNMENT 
LIST WITH RIGHT_HALF LIST. #/ 
dO 
N = 1 BY 1 WHILE 
(N => SIZECASSIGNMENT))3 
IF 
(GET_NO (ASSIGNMENT ND DH(*,?) 
THEN 
DO; 
CALL DELETE_NO(CASSIGNMENT,NDS 
CALL INSERT_LISTCASSIGNMENT,N, 
RIGHT_HALF)$ 
END; 
ENO; 
/* LINK RIGHT_HALF LIST TO 
ASSIGNMENT LIST. ®/ 
CALL LINK(CASSIGNMENT, RIGHT_HALF)3 
OVER: 
END 
A_EXPAND3$ 


Figure 2.38A. Expanding an assignment statement 


ies 
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Data List 
(before reference) 


a: DoD BDL bELBELbEL BED 
kT bE REL PEN 

2 CPS LbL LD bERLAELRELBIT 
ALC PELPELbeLRER 

i: CD KID ROL REL ROLE 
CCRhELPELAELPELbPEN 


Reference (after reference) : 
uo: [} >a PEL ELREL ELBE 
BC RELBELHEL YL HEL 
biel HELL PEL HELHEN 
2 CSC PELRELBHELbELbEL 
AL RELRELREL REL 
el EL oo 
i) C} CD PELRCLR ELBE REL 
GBD RECROCRELRELBEL 
CU BhELHELbELPELPEN 
Lai 


Figure 2.38B, Examples of references to the A_EXPAND subroutine 











A_EXPAND(L1) 





A_EXPAND(L2) 

























A_EXPAND(L3) 





A_EXPANDIL4) 


PLEXPAND? 


DECLARE 


PROCEDURE (PICTURE) 3 


C CHARACTER(1),» 

(PICTURE, EXPANDED) POINTER, 

FACTOR CHARACTER (6) VARYING? 

/* INITIALIZE. */ 

EXPANDED = NULL? 

/* INSERT LEFT END OF PICTURE LIST 
(UP TO AND INCLUDING FIRST QUOTE) AT 
FRONT OF EXPANDED LIST. */ 


QUOTE1L:?: 
C = REMOVE_FO(PICTURE)$ 
CALL INSERT_LOCEXPANDED,C); 
F 
Pap ery 
THEN | 
GO TO 
QUOTE]; 
/* SCAN REMAINDER OF PICTURE LIST 
(UP TO AND INCLUDING CLOSING 
QUOTE). */ 
QUOTE2: 
C = REMOVE_FD(PICTURE)$ 
F 
a eeney 
THEN 
GO TO 
FINISH; 
/* WHEN CHARACTER IS LEFT PAREN, GO 
TO STATEMENTS THAT OBTAIN REPETITION 
FACTOR. */ 
IF 
(Cc = *(") 
THEN 
GO TO 


REPETITION_FACTORS 

/* OTHERWISE, INSERT CHARACTER AT 
END OF EXPANDED LIST AND GET NEXT 
CHARACTER. */ 

CALL INSERT_LOCEXPANDED, C); 


Figure 2.39A. Expanding a picture specification 


GO TO 
QUOTE23 
/* INSERT REPETITION FACTOR IN 
FACTOR. */ 
REPETITION_FACTOR: 
FACTOR = * °3 
NEXT_CHARACTER: 
C = REMOVE_FD(PICTURE); 
1F 
(C = *)*) 
THEN 
GO TO 
EXPAND; 
FACTOR = FACTORIIC; 
GO TO 
NEXT_CHARACTER3 
/* INSERT NEXT CHARACTER THE 
NUMBER OF TIMES SPECIFIED BY FACTOR. 


*/ 
EXPAND: 
C = REMOVE_FO(PICTURE)3 
00 
N = 1 TO FACTOR? 
CALL INSERT_LOCEXPANDED,C)3 
ENO; 
/* GET NEXT CHARACTER. */ 
GO TO : 


QUOTE23 
/*# AT THIS POINT, EXPANSION IS 
COMPLETE. INSERT FINAL QUOTE AT END 
OF EXPANODEO LIST AND LINK EXPANDED 
LIST TO PICTURE LIST. */ 

FINISH: 
CALL INSERT_LO(EXPANOED,C)3 
CALL LINK(PICTURE, EXPANDED)3 

ENO. 
P_EXPAND3 


T7 
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Data List 
(before reference) 


P_EXPANDI(L1) 


ee 
Pols 
9} 
P_EXPAND(L2) | L2: | [—p P| | 


P_EXPAND(L3) 


eal 
ale 
Bas 
Lod 
Z| 
(of | 


[c} 
ae 
Oe 


cl 
zi | 
iN 


Figure 2.39B. Examples of references to the P EXPAND subroutine 


ae 
as 
es 





Contracting a Picture Specification 


Figures 2.40A and 2.40B present the P_CNTRT subrou- 
tine procedure, which accepts a PICTURE specification in 
list form and contracts the list by replacing repeated char- 
acter sequences five or more in length with repetition 
factors. 


This procedure may be treated as the inverse of the 
P_ EXPAND procedure (Figures 2.39A and 2.39B). 


p_CNTRT3 
PROCFOURE (PICTURED S$ 

DECLARE 
C CHARACTER(1 Ds 
(PICTURE, FACTOR_LIST) POINTER, 
(NeMelel) FIXED DECIMAL (5), 
REPETITION_FACTOR PICTURE °Z22229% 4 
FACTOR_STRING CHARACTER (533 
/@ INITIALIZE. #/ 
FACTOR_LIST = NULL? 
/* FIND POSITION OF FIRST QUOTE IN 
PICTURE LIST. %/ 


DO 
N= 1 BY 13 
IF 
(GET_NO(PICTURE,N) = 999°) 
THEN 
003 
NeN 13 
GO TO 
NEXT _ CHARACTER S$ 
END3 
ENO$ 


/* SCAN PICTURE LIST FOR CHARACTER 
SEQUENCES OF LENGTH FIVE OR MORE. #%/ 
NEXT_CHARACTER?: 
C = GET_NO(PICTURE,N)$ 
/* IF SECOND QUOTE IS FOUND, 
PROGRAM IS FINISHED. */ 
IF 
(C Zz eece) 
THEN 
RETURNS 
/* TEST FOR REPEATED SEQUENCE. %/ 
DO 
M=zWN*#i1 BY 13 
IF 
(GET_ND (PICTURE »M)-~2C) 
THEN 
GO TO 
LENGTH_TEST>$ 
END; 
/* IF SEQUENCE-LENGTH IS LESS THAN 
FIVE, RESUME SEARCH */ 
LENGTH_TESTs: 
l= 
IF 
(L<5) 


Figure 2.40A. Contracting a picture specification 


Adding Variable-Length Integers 


Figures 2.41. A and 2.41B present the ADD_INT subrou- 
tine procedure, which adds two variable-length integers in 
list form. The length of each integer is arbitrary and is 
limited only by available storage. The integers need not 
have equal lengths. 

ADD _INT assumes that the argument lists contain only 
numeric characters (signs and decimal points are not per- 
mitted). The integer in the first argument list is added to 
the integer in the second argument list. The third argument 
receives the result list. 


THEN 
DO; 
N = M$ 
GO TO 
NEXT_CHARACTERS$ 
END; 
/* CONVERT SEQUENCE-LENGTH TO 
EDITED STRING WITH LEADING ZEROS 
SUPPRESSED. */ 
REPETITION_FACTOR = L3 
/* ASSIGN EDITED STRING TO 
FACTOR_STRING, WHICH HAS ATTRIBUTES 
REQUIRED BY THE STRING_TO_LIST 
SUBROUTINE. */ 
FACTOR_STRING = REPETITION_FACTOR; 
/* CONVERT FACTOR_STRING TO 
FACTOR_LIST. */ 
CALL STRING_TO_LIST(FACTOR_STRING, 
FACTOR_LIST)$ 
/* DELETE LEADING BLANKS FROM 
FACTOR_LLIST. */ 
00 I = 1 BY 13 
IF 

(GET_FO(FACTOR_LIST) 

THEN 

GO TO 

PARENTHESES3 
CALL DELETE_FOCFACTOR_LIST)3 


END3 
/@ INSERT PARENTHESES AT FRONT ANO 
BACK OF FACTOR LIST. %/ 
PARENTHESES? 
CALL INSERT_FOCEACTOR_LLIST, *C°)3 
CALL INSERT_LOCFACTOR_LIST.*9*)3 
/* CONTRACT REPEATED SEQUENCE ANDO 
INSERT FACTOR_LIST. %/ 
CALL DELETE_SUB( PICTURE, Ny L-1)93 
CALL INSERT_LIST(PICTURE,N, 
FACTOR_LIST)3 
/* SET N TO POSITION OF NEXT 
CHARACTER. DELETE FACTOR_LIST. 
NEXT_CHARACTER. %/ 
N= N # SIZECFACTOR_LIST) * 13 
CALL DELETE_LISTCFACTOR_LIST): 
GO TO 
NEXT_CHARACTER; 


GO TO 


END 
P_CNTRT$ 
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Data List 
(before reference) 





























Subroutine 
Reference 


P_CNTRT(L1) 


P_CNTRT(L2) 


P_CNTRT(L3) 





L2: 


L1: 


CO} HEHEHE HEHE 
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Data List 
(after reference) 





he ee 
CE of a. Ue eee 


WOT eTE DT EPLEEN 
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Figure 2.40B. Examples of references to the P_CNTRT subroutine 


PROCEDURE (ADDEND1 » ADDEND2,SUM) 3 


(ADDEND1 », ADDEND2,SUM) POINTER, 
(CARRY, DIGIT1, DIGIT2) 
CHARACTER(1), 

1 SUM_TABLE(021,029,0:39), 
2 TENS CHARACTER(1), 

2 UNITS CHARACTER(1), 
SUMS_OF_DIGITS_AND_CARRY 
CHARACTER(400) DEFINED SUM_TABLES$ 
7* INITIALIZE SUM_TABLE. */ 
SUMS_OF_DIGITS_AND_CARRY = 
*00010203040506070809' 
*010203040506070809108 
*02030405060708091011' 
*03040506070809101112! 
*04050607080910111213' 
*05060708091011121314' 
*06070809101112131415' 
*07080910111213141516' 
*908091011121314151617' 
°09101112131415161718' 
*01020304050607080910! 
*02030405060708091011' 
*03040506070809101112' 
*04050607080910111213! 
*05060708091011121314' 
*06070809101112131415' 
*07080910111213141516° 
*08091011121314151617' 
*09101112131415161718° 
*10111213141516171819'; 
CLEAR SUM AND CARRY. */ 
SUM = NULLS$ 

CARRY = "0°35 

/* TEST FOR NULL LISTS */ 
IF ((AODEND] = NULL) & 
(ADDEND2 = NULL)) 

THEN DO; 

CALL INSERT_FD(SUM,*0*)3 
RETURNS 

END$ 

IF ADOEND] = NULL 

THEN DO$ 

SUM = ADDENO2; 

RETURNS 

ENO; 

IF AODDEND2 = NULL 


~ 
# 


Figure 2.41A. Adding variable-length integers 


THEN DO$ 

SUM = ADDEND1$ 

RETURNS 

ENO; 

/* INSERT LEADING ZERO AT FRONT OF 
ADDEND1 LIST AND ADOEND2 LIST. */ 
CALL INSERT_FO(ADDEND1], *0*)5 

CALL INSERT_FOCADDEND2, '0*)5 

/* ENTER LOOP THAT COMPUTES SUM OF 
ADDEND1] ANO ADOEND2. */ 


LOOP : 


DO WHILE((ADDENO1] -~= NULL) | 
(ADDEND2 -~= NULL))3 
/* REMOVE RIGHTMOST OIGITS OF 
ADDENOS, AND ASSIGN THEM TO DIGITI 
ANO DIGIT2. */ 
DIGITL = REMOVE_LD(ADDEND1)$ 

IF 
(OIGITL = * *) 


THEN 


OIGIT1 = "0% 

OIGIT2 = REMOVE_LO(ADDEND2)3 
IF 

(OIGIT2 = * *) 


THEN 


DIGIT2 = "0%; 

/* OBTAIN UNITS DIGIT FOR THE SUM OF 
CARRY, DIGIT2, ANDO DIGIT13 AND 
INSERT UNITS DIGIT IN THE FIRST 
POSITION OF SUM LIST. */ 

CALL INSERT_FO(SUM, UNITS(CARRY, 
DIGIT2, OIGIT1))3 

/* SET CARRY EQUAL TO TENS DIGIT 
FROM THE SUM OF CARRY, DIGIT2, ANO 
OIGIT1L. ¥*/ 
CARRY#TENS(CARRY,»DIGIT2,DIGIT1)3 


ENO LOOP$ 


ZEROS: 


ENO 


/* REMOVE LEADING ZEROS FROM SUM */ 


IF (GET_LFD(SUM) = *0*) 

THEN 003 

CALL OELETE_FO(SUM);3 

GO TO ZEROS}; 

END; 

/* IF SUM IS NULL» INSERT 0 */ 
IF SUM = NULL 

THEN CALL INSERT_FD( SUM, *0*)3 


ADO_INT$ 
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DIGIT1 


of 00 | 01 | o2 | 03 | 04 | 08 | 06 | 07 | 08 | 09 
1 || 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10) 


ee 


Sums of digits when previous carry is zero 


DIGIT1 


= © 
w= © | 
(e¥) ~J 


—_ 


Sums of digits when previous carry is one 





Figure 2.41B. Tables for the sums of two digits and a previous 
carry 


The procedure uses a table lookup technique to add the 
two integers digit by digit from right to left. Figure 2.41B 
contains illustrations of the tables used by ADD_INT. The 
first table gives the sums of digit pairs when no carry is 
involved from the previous digit sum. The sums in the 
second table account for a carry of one from the previous 
digit sum. The sum of the rightmost digits in the two in- 
tegers always assumes a previous carry of zero. The digit in 
the tens position of a sum specifies the carry for the next 
digit pair. 
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The following example shows how the tables are used: 


1 1 0 0 Carried digits 


2 9 7 8 Second integer 


3 ] First integer 


3 0 0 9 Sum 


The first digit pair is 1 and 8, and it assumes a previous 
carry of 0; therefore, the first table is used to obtain the 
sum 09. The 9 in the sum becomes the units digit in the 
final result, and the 0 becomes the carry for the second 
digit pair. 

The second digit pair is 3 and 7, and its sum (10) is 
obtained from the first table. The 0 in this sum becomes 
the tens digit in the final result, and the 1 becomes the 
carry for the third digit pair. 

At this point, all digits have been used in the first in- 
teger; therefore, zeros are assumed in the remaining posi- 
tions until the final result is obtained. The third digit pair, 
then, is 0 and 9, and its associated sum (10) is obtained 


‘from the second table, since the previous carry is 1. The 0 


in this sum forms the hundreds digit of the final result, and 
the 1 is carried to the next position. 

The fourth digit pair is 0 and 2, and its associated sum 
(03) is obtained from the second table. The 3 in this sum 
becomes the leftmost digit in the final result, which is 
3009. 

ADD_INT combines the tables in Figure 2.41B into 
one three-dimensional array. It is then possible to use the 
two digits being added and the carry digit as subscript 
values in references to the associated sum in the array. The 
sums are also arranged as structures in the array, so that 
the units and tens digits of each sum can be referred to 
separately. 

The aggregate total is contained in the list named SUM. 
The advantage of using data lists in this application is 
that they do not impose a specific maximum length on the 
integers being added. As long as the combined lengths of 
the two integers do not exceed available list storage, they 

can have any individual lengths. 


Subtracting Variable-Length Integers 


_ Figures 2.42A and 2.42B present the SUB_INT subroutine 


procedure, which subtracts two variable-length integers in 
list form. The length of each integer is arbitrary and is 
limited only by available storage. The integers need not 
have equal lengths. 


PROCEDURE (SUBTRAHEND» MINUEND, 


DIFFERENCE); 
(BORROW, OIGIT1, OIGIT2) 
CHARACTER(1), 
(SUBTRAHEND, MINUEND, 
POINTER, 

1 DIFFERENCE_TABLE(0:21902990:9)¢ 
2 TENS CHARACTER(1), 

2 UNITS CHARACTER(1), 
DIFFERENCES_AND_BORROWEO_DIGITS 
CHARACTER(400) 

DEFINED DIFFERENCE_TABLE; 

/* INITIALIZE OIFFERENCE_TABLE. */ 
DIFFERENCES_AND_BORROWEC_DIGITS = 
£00191817161514131211° 
°01001918171615141312° 
°02010019181716151413° 
*03020100191817161514° 
*04030201001918171615° 
*05040302010019181716°* 
*06050403020100191817°* 
*07060504030201001918° 
*08070605040302010019°8 
*090807060504030201008 
*19181716151413121110° 
*00191817161514131211° 
°01001918171615141312° 
*02010019181716151413° 
*03020100191817161514°* 
*04030201001918171615°" 
*05040302010019181716* 
*06050403020100191817° 
*07060504030201001918° 
*08070605040302010019°; 

CLEAR OIFFERENCE AND BORROW */ 
OIFFERENCE = NULL3 

BORROW = °0°; 


DIFFERENCE) 


~ 
% 


/* TEST FOR NULL LISTS */ 
IF ((SUBTRAHEND = NULL) & 
(MINUEND = NULL)? 

THEN DO3 


CALL INSERT_FO(OIFFERENCE,*0*)3 
RETURNS 

ENO; 

IF SUBTRAHEND = NULL 

THEN DO; 


Figure 2.42A. Subtracting variable-length integers 


LOO 


Pe: 


DIFFERENCE = MINUENDS 


/* ENTER LOOP THAT COMPUTES 
DIFFERENCE OF SUBTRAHEND AND 
MINUEND. */ 


DO WHILE( (SUBTRAHEND+=NULL) { ° 

(MINUEND == NULL))3 

/*® REMOVE RIGHTMOST DIGITS OF 

SUBTRAHEND AND MINUEND ANO ASSIGN 

THEM TO DIGIT1 ANDO OIGIT2. */ 

DIGIT] = REMOVE_LO(SUBTRAHEND)$ 
IF 

(DIGITL = * *) 


THEN 


DIGITL = *0%$ 

DIGIT2 = REMOVE_LOCMINUEND)$ 
IF 

(DIGIT2 = * °) 


THEN 


ENO 


DIGIT2 = 0%; 
/* OBTAIN UNITS DIGIT FROM THE 
DIFFERENCE OF DIGIT2 AND THE SUM OF 
DIGIT1 AND BORROW: 

AND INSERT UNITS DIGIT IN THE 

FIRST POSITION OF OIFFERENCE LIST. */ 
CALL INSERT_FOCOIFFERENCE, UNITS 
(BORROW, DIGIT2, DIGIT1))3 

/* SET BORROW EQUAL TO TENS DIGIT 
FROM THE OLFFERENCE OF DIGIT2 AND 

THE SUM OF DIGIT1 AND BORROW. */ 
BORROW = TENS(BORROW, DIGIT2, 
DIGIT1)3 

LOOP: 

/* REMOVE LEADING 
DIFFERENCE LIST */ 


ZEROS FROM 


ZEROS: 


END 


IF (GET_LFOCOITFFERENCE) = *0*) 
THEN D003 

CALL DELETE_FO(OIFFERENCE)3 
GO TO ZEROS; 

END3 

/* IF OIFFERENCESNULL, 
IF OILFFERENCE = NULL 
THEN CALL INSERT_FOCOIFFERENCE,*0*)3 


INSERT 0 @/ 


SUB_LINT3 
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SUBTRAHEND 


18 | 17 | 16 | 15 | 14 | 13] 12 | 11] 

pas [af 9 [1 

fie [15 

cai ra 
17 

ne. 


ND 


for eee 


ne: 
rie 
9) 
r09) 


—_ — fo 
~J &} 


Differences of digits when previous borrow is zero 


errr etanacetenmeneseemntieamee 


SUBTRAHEND 


Differences of digits when previous borrow is one 


Figure 2.42B. Tables for the differences of two digits with and 
without a previous borrow 


SUB_INT assumes that the argument lists contain only 
numeric characters (signs and decimal points are not per- 
mitted). The integer in the first argument list (the subtra- 
hend) is subtracted from the integer in the second 
argument list (the minuend). The value of the subtrahend 
must not exceed the value of the minuend. The third argu- 
ment receives the result list. 

The procedure uses a table lookup technique to sub- 
tract the two integers digit by digit from right to left. 
Figure 2.42B contains illustrations of the tables used by 
SUB_INT. The first table gives the differences of digit 
pairs when no borrow was required by the previous digit 
pair to the right. The entries in the second table account 
for a borrow of one by the previous digit pair to the right. 
The difference of the rightmost digits in the two integers 
always assumes a previous borrow of zero. 
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The digit in the tens position of a table entry specifies 
the amount borrowed from the minuend digit on the left 
to obtain the difference of two digits. This difference 
appears as the units digit in the table entry. 

The following example shows how the tables are used: 


1 ] 0 0 Borrowed digits 


3 0 0 9 Minuend 
3 1 Subtrahend 
2 9 7 8 Difference 


The first digit pair is 1 and 9, and it assumes a previous 
borrow of 0; therefore, the first table is used to obtain the 
associated entry 08. The 8 in this entry becomes the units 
digit in the final result, and the O specifies the amount 
borrowed from the minuend digit on the left. 

The second digit pair is 3 and 0, and its associated entry 
(17) is obtained from the first table. The 7 in this entry 
becomes the tens digit in the final result, and the 1 speci- 
fies the amount borrowed. 

At this point, all digits have been used in the subtra- 
hend; therefore, zeros are assumed in the remaining posi- 
tions of the subtrahend until the final result is obtained. 
The third digit pair, then, is 0 and O, and its associated 
entry (19) is obtained from the second table, since the 
previous borrow is 1. The 9 in this entry becomes the 
hundreds digit of the final result, and the 1 specifies the 
amount borrowed. 

The fourth digit pair is 0 and 3, and its associated entry 
(02) is obtained from the second table. The 2 in this entry 
becomes the leftmost digit in the final result, which is 
2978. 

SUB_INT combines the tables in Figure 2.42B into one 


_ three-dimensional array. It is then possible to use the | 


two digits being subtracted and the previously borrowed 
digit as subscript values in references to the associated 
entry in the array. The entries are also arranged as struc- 
tures in the array, so that the units and tens digits of each 
entry can be referred to separately. 


Gathering Declare Statements in a Procedure 


So far the applications in this section have been developed 
in subroutine form. As a result, the subroutines have as- 
sumed the existence of a list of available storage com- 
ponents. The present application is developed as a 
complete program, which generates a list of available stor- 
age components for list-processing techniques within the 
program. 

Figure 2.43 presents the DGATHER program, which 
gathers the DECLARE statements in a PL/I procedure so 
that they appear as a single DECLARE statement at the 
front of the procedure. 


OGATHER? 
PROCEDURE? 
DECLARE 


SPACE AREA(327T6T)» 

(DECLARE_LIST, NEW_DECLARE, 
MARGIN» PROCEDURE, AVAIL EXTERNAL» 
SAVE_LIST) POINTER, 

CARD(80) CHARACTER(1LD, 

C CHARACTER (1)>» 

DECLARE_STRING CHARACTER(9), 
DECLARE_TABLE(4) CHARACTER(9),y 
(STRING_SWITCH, COMMENT_SWITCH, 
FINISH SWITCH) 

BIT(L) INITIAL (*O"°B), 

(Ne TeFIRST_SEMICOLON,PROCEOURE_SIZE) 
FIXED DECIMAL(5) INITIAL(O)3 

/* AT THE END OF THE SYSIN FILEs 
COMPUTE THE SIZE OF THE PROCEDURE 
LIST AND GO TO SCAN. */ 

ON ENDFILE(SYSIN) 


BEGINS 


END: 


PROCEDURE_SIZE = SIZE(PROCEDURE)$ 


GO TO 
SCANS 


*/ 
PROCEDURE, 


/* INITIALIZE. 
AVAIL, MARGIN, 
DECLARE_LIST, 
NEW_DECLARE, SAVE_LIST = NULL$ 

CALL AREA_OPEN(SPACE, AVAIL) 
DECLARE_TABLE(1) = *3DECLARE '3 
DECLARE_TABLE(2) = *;DECLARE('S 
DECLARE_TABLE(3) = * DECLARE °'3 
DECLARE_TABLE(4) = * DECLARE('S 
CALL STRING_TO_LLIST(*DECLARE ', 
NEW_DECLARE)$ 

/* READ INPUT CARDS. FOR EACH CARD, 
INSERT COLUMNS 1 AND 73 THROUGH 80 
AT END OF MARGIN LIST, AND 

COLUMNS 2 THROUGH 72 AT END OF 
PROCEDURE LIST. */ 


INPUT: 


DO 


ENO; 
DO 


END; 


SCAN 
DO 


GET 
EDIT (CARD) (80 A(1))3$ 
CALL INSERT_LD(MARGIN, CARD(1))35 

N = 2 TO 723 

CALL INSERT_LO(PROCEDURE,CARDINI)$ 


N = 73 TO 80; 
CALL INSERT_LO(MARGIN, CARD(N))5 
GO TO 
INPUT; 
/* SCAN PROCEDURE LIST FOR DECLARE 
STATEMENTS. */ 


N = 1 TO PROCEDURE_SIZE; 
/* GET NEXT CHARACTER AND TEST IT. 
C = GET_NDO( PROCEDURE, N); 
ree 
THEN 
GO 


*/ 


TO 
STRING_TEST; 
IF 
(C="/*) 


Figure 2.43. Gathering declare statements 


THEN 


GO TO 
COMMENT_TESTS 
IF 
STRING_SWITCH 
THEN 
GO TO 
END_SCAN$ 
IF 
COMMENT_SWITCH 
THEN 
GO TO 
END_SCAN; 
IF 
(FIRST_SEMICOLON = QO) 
THEN 
IF 
(C = 3%) 
THEN 


FIRST_SEMICOLON = N35 


/* TEST FOR DECLARE STATEMENT. 


FINO_DECLARE: 
CALL ASSIGN_SUB(DECLARE_LIST, 
PROCEDURE», Ny 993 


*/ 


CALL LIST_TO_LSTRING(DECLARE_LIST, 


DECLARE_STRING)$ 


00 
I = 1 TO 43 
IF 
(DECLARE_STRING = DECLARE_TABLE(1!I)) 
THEN 
003 
/* REPLACE KEYWORD DECLARE WITH BLANKS */ 
DO N= N +1 TON # 73 
CALL REPLACE_ND( PROCEDURE ,Ny,* *')5 
END; 
GO TO 
PROCESS_DECLARE3$ 
END$ 
END; 
GO TO 
END_SCANS$ 
/* PROCESS DECLARE STATEMENT. */ 
PROCESS_DECLARE: 
/* INSERT CECEARE STATEMENT 
WITHOUT KEYWORD DECE ARE AND 
TERMINATING SEMEPCOEON AT END OF 
NEWLDECLARE LIST. */ 
DO N = N RY D5 
C = GETLNUCRPROCE DURE oN) 5 
IF GC w= 3 THEN DOS 
CALL INSFERT_LDUNFW_LDECLARE,C)5$ 
CALL REPLACE NDC PROCEDURE N,® *)5 
END; 
ELSE DO; 
CALL INSERT_LO(NEW_DECL ARE, *%_")35 
CALL REPLACE_ND( PROCEDURE ,N,® 3 
N=N- 15 
GO TO END_SCAN; 
END$ 


END PROCESS_DECLARE; 
/* TEST FCR START OR END OF 


STRING. */ 
STRING_LTEST: 
IF 
STRING_SWITCH 
THEN 
IF 


(GET_ND(PROCEDURE, N + 1) = 


eeee) 
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THEN 
N=N 413 
ELSE 
STRING_SWITCH = °0°B3 
ELSE ae 
STRING_SWITCH = °1°B3 
GO TO 
END_SCAN3 
/* TEST FOR START OR END OF 
COMMENT. */ 
COMMENT_TEST: 
IF 
COMMENT_SWITCH 
THEN 
IF 
GET_ND(PROCEOURE,N-1) ="#! 
THEN 
COMMENT_SWITCH = *0°B; 
ELSE; 
ELSE 
IF 
GET_ND( PROCEDURE, N + 1) = ¢#? 
THEN 
00; 
COMMENT_SWITCH = °1°B; 
N=N +413 
END; 
END_SCAN: 
END 
SCANS 
/* TERMINATE NEW_DECLARE LIST 
WITH A SEMICOLON */ 
CALL REPLACE_LO(NEW_DECLARE,"3")3 
/* RECONSTRUCT ORIGINAL PROCEDURE 
AND PLACE NEW_DECLARE LIST BEHIND 
LEADING PROCEDURE STATEMENT. */ 
/* SPLIT PROCEDURE LIST AFTER FIRST 
SEMICOLON. */ 
CALL SPLIT( PROCEDURE, 
FIRST_SEMICOLON + 1» SAVE_LIST)3 
PuT 
PAGE; 
/* PRINT MERGED PROCEDURE AND 
MARGIN LISTS. */ 
OUTPUT1L: 
C = REMOVE_FD(MARGIN)$ 
put 
EDIT(CYCACL) DS 
00 
N = 1 TO 713 
C = REMOVE_FO( PROCEDURE); 
PUT 
EDIT(CVCACLIDS 


00 : 

N= 1 TO 83 

C = REMOVE_FO( MARGIN) 
PUT 

EDIT(CI(AC1I)S 


Figure 2.43. Gathering declare statement (Continued) 
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END; 
PUT 
SKIP$ 
IF 
(PROCEDURE-=NULL) 
THEN 
GO TO 
OUTPUTL;3 
/* IF FINISH SWITCH IS ONE, GO TO 
ENO_OCL_GATHER. */ 
IF 
FINISH SWITCH 
THEN 
GO TO 
ENO_OCL_GATHER; 
/* PRINT NEW DECLARE LIST WITH BLANK 
MARGINS. *%/ 
OUTPUT2: 
PuT 
EDIT(® *")(ACLIDS 
00 
N= 170 713 
C = REMOVE_FD(NEW_DECLARE); 
PuT 
EDITICI(CACL))3 
END; 
PUT 
SKIPS 
1F 
(NEW_DECLARE==NULL ) 
THEN 
Go TO 
OUTPUT23 
/* LINK REMAINDER OF PROCEDURE IN 
SAVE_LIST TO PROCEOURE_LIST. @/ 
CALL LINK( PROCEDURE, SAVE_LIST): 
/* POSITION REMAINDER OF PROCEDURE 
SO THAT ORIGINAL FORMAT IS NOT 
DISTURBED. *%/ 
I = MOD(FIRST_SEMICOLON, 71) @ 13 
PuT 
EDITC® *)CCOLUMNCT), ACL1)D3 
DO 
N= 1 TO (Tl-1I)3 
C = REMOVE_FD( PROCEDURE); 


EOIT (Cd) CACLIDS 


SKIP S$ 
/@ TURN FINISH_SWITCH ON, AND 
CONTINUE PRINTING REMAINOER OF 
PROCEDURE_LIST AT OUTPUTL. %/ 
FINISH-SWITCH = *1°8; 
GO TO 
OUTPUT: 
ENO_DOCL_GATHER: 
ENO 
OGATHER }$ 


DGATHER obtains the procedure from the standard 
system-input file (SYSIN), gathers the DECLARE state- 
ments at the front of the procedure, and prints the pro- 
cedure on the standard system-output file (SYSPRINT). 
As a simplification, DGATHER does not permit other 
procedures or begin blocks to appear in the procedure 
being processed. The number of DECLARE statements in 
the procedure is arbitrary, and they may appear anywhere 
within the procedure. 

The major processing steps performed by DGATHER 
are to: 

1. Generate the list of available storage components, 
AVAIL, in the area called SPACE 

2. Obtain successive input cards and insert column 1 
and columns 73 through 80 into the MARGIN list and 
columns 2 through 72 into the PROCEDURE list 

3. Search for DECLARE statements and form a 
NEW_DECLARE list; skip character strings and PL/I 
comments when searching for DECLARE statements 

4. Remove all DECLARE statements from the pro- 
cedure and insert the NEW_ DECLARE list behind the 
leading PROCEDURE statement 


5. Print the procedure, maintaining as much of the orig- 


inal format as possible 


STORAGE_AREA 


These steps provide an elementary illustration of how 
list-processing techniques can be used by a compiler to re- 
organize and analyze a source program before it it trans- 
lated into an object program. 


Note: All of the sample programs in Chapter 2 were 
internal to a single containing procedure. Each entry name 
was declared in the containing procedure. 


REVIEW OF SIMPLE DATA LISTS 


Chapter 2 shows how to generate allocations of based stor- 
age throughout an area and how to link such allocations 
into a list of available storage components (see AVAIL in 
Figure 2.44). It also shows how to develop subroutines and 
functions that use available storage components to form 
new lists. The subroutines and functions are developed in 
hierarchical fashion so that routines concerned with the 
primitive aspects of storage manipulation can be used in 
turn to create higher level procedures. This approach limits 
the number of procedures that deal with environmental 
factors and permits the complete collection of subroutines 
and functions to possess an application-oriented emphasis. 






L1: 


L2: 


AVAIL: 


Al Fes] pect | 
FT isl 
at] Pez) Pes] om Eas 
Lt PLL RL LRP 
HT RPLERPLLPLL RL 


ee. we. we. ee 





Oo] Fm! 












Figure 2.44. Simple data lists linked within an area 
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The main advantage of simple data lists over array and 
structure organizations is that lists need reserve only the 
storage they are currently using. As a list grows, new stor- 
age is obtained from the list of available storage com- 
ponents. Similarly, when list components become free, 
they are returned (relinked) to the list of available storage 
components. Asa result, the same storage can be used by 
many different lists during the course of program execu- 
tion. Sharing storage in this manner reduces the amount of 
storage that might lie dormant within a list in anticipation 
of maximum storage requirements for the list. 
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SUMMARY 


1. Chapter 2 shows how to organize and process simple 
data lists in which each component contains a single data 
character. 

2. Representative subroutines and functions are pre- 
sented for the following types of operations: 

a. Creating a list of available storage components 
b. Manipulating the elements of list components 
c. Manipulating list components 

d. Manipulating sublists and lists 

e. Manipulating lists recursively 

3. Primitive subroutines and functions are developed 
first and are used in turn to create higher level procedures. 


Chapter 3: Complex Data Lists 


This chapter shows how the simple list organization of 
Chapter 2 may be extended to obtain more general types 
of data lists. These extensions fall into three categories, 
which involve: 

1. Using other types of data in list components besides 
single characters 

2. Storing descriptive information about a list in the 
head of the list 

3. Using additional pointer elements to obtain alterna- 
tive orderings of list components besides a simple linear 
ordering 


The types of lists produced by these extensions are re- 
ferred to collectively as complex data lists to distinguish 
them from the simple list organization presented in Chap- 
ter 2. No attempt is made, however, at developing a col- 
lection of subroutines and functions that organize and 
process complex lists. The intent of this chapter is to 
indicate how the techniques of the previous chapter may 
be applied to more general list organizations. 


MORE GENERAL DATA IN LIST COMPONENTS 


An elementary extension that can be made to simple list 
organization involves replacing the single-character ele- 
ments of list components with more general types of data. 
As Figure 3.1 illustrates, data of any type and precision 
may appear in list components. Even arrays and structures 
are permitted. List-processing techniques, as a result, can 
be applied to numeric as well as nonnumeric data, and to 
data collections such as tables, records, and reports. 

Many of the procedures developed in Chapter 2 still 
apply to lists that contain more general types of data. 
Figure 3.2, for example, shows how a list of available stor- 
age components may be created for lists that contain ar- 
rays of structures. Except for differences in the declara- 
tions of the list components, this procedure is identical to 
the corresponding procedure in Figure 2.1B. 

It is also possible to use the compile-time facilities of 
PL/I to simplify the creation of list-processing procedures 
for new types of data in list components. Figure 3.3 shows 
how a general version of the AREA OPEN procedure may 
be created for different list components. The procedure 
contains two compile-time statements. The first statement 
(%DECLARE) defines the identifier LIST COMPONENT 
to be a compile-time character-string variable. The second 
statement is a compile-time assignment statement that 
assigns a character-string value to LIST COMPONENT. 


These two statements cause the PL/I compiler to 
modify the text of AREA OPEN before its machine- 
language equivalent is generated. Each appearance of the 
identifier LIST COMPONENT in AREA_ OPEN is re- 
placed with the value of the identifier. Since the value of 
LIST COMPONENT in this example is identical to the 
component declaration used throughout Chapter 2, Figure 
3.3 is equivalent to the AREA OPEN procedure in Figure 
2.1B. 

Assigning a different component declaration as the 
value of LIST COMPONENT would produce a corre- 
sponding change in the AREA OPEN procedure and avoid 
the need for separate copies of the subroutine. 

Similar use of compile-time statements can be applied 
to other list-processing procedures, but some function 
procedures may require extensive modification or com- 
plete replacement by equivalent subroutine procedures. 
For example, a function procedure cannot return the value 
of a data item that is not an element item. Consequently, a 
list-processing function such as GET_ND, which gets the 
data item in the nth component of a data list, cannot re- 
turn the specified data item when it is either an array or a 
structure. Retrieval of the array or structure would have to 
be made with a subroutine that uses a parameter to return 
the desired item. 

Other compile-time statements can be used to choose 
among alternative versions of procedures stored in a list- 
processing library. 

An introductory presentation of the compile-time facili- 
ties and their applications appear in the IBM publication 
An Introduction to the Compile-Time Facilities of PL/I 
(SC20-1689). 


DESCRIPTIVE DATA IN LIST HEADS 


A further generalization of list organization involves the 
head of a list, which so far has been restricted to a pointer 
variable that specifies the address of the first list com- 
ponent. The head of a list can be enlarged, however, so 
that it contains descriptive information about the list be- 
sides the location of its first component. 

The size of a list, for example, need not be computed 
each time it is requested. The size can be stored in the 
head of the list, where it is readily obtained by direct refer- 
ence. With this convention, procedures that insert or delete 
list components would automatically adjust the size value 
in the head. 
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06 


Component Declaration Example of Data List | 


COMPONENT BASED(P), » Lo t9064 TT} of 18023 TT} of 20007 Tp of aares 


2 DATA FIXED DECIMAL(5), 
2 POINTER POINTER Fixed-point decimal items in a data list 


COMPONENT BASEDIP), 
2 DATA(3) FIXED DECIMAL(5), 08143 


-2 POINTER POINTER 21169 


COMPONENT BASEDIP), 
2 DATA, _ 

3 PART# PICTURE ‘AXA’, 

3 QUANTITY FIXED DECIMAL(2), | Structures in a data list 
2 POINTER POINTER | 


COMPONENT BASEDIP), 

2 DATA(2),. 
3 VOLUME FIXED DECIMAL(3), 
3 COST FIXED DECIMAL(2), 


2 POINTER POINTER 
Arrays of structures in a data list 





Figure 3.1. Examples of data lists with different types of components 


AREA_OPEN2: 
PROCEDURE (AREA2,LIST)$ 
DECLARE 
AREA2 AREA(*#), 
(LIST, T) POINTER, 
1 COMPONENT2 BASED(P), 
2 DATA CHARACTER(1), 
2 VOLUME FIXED DECIMAL(3), 
2 COST FIXED DECIMAL(2). 
2 POINTER POINTERS 
ON AREA 
BEGINS 
IF 
PazNULL 
THEN 
P=>POINTER # NULL3 
GO TO 
END_AREA_OPEN23 
END3 
P = NULL3 
ALLOCATE COMPONENT2 INC AREA2Z)SET(P)3 
LIST = P3 
L3 
T = P3 
ALLOCATE COMPONENT2 INCAREA2Z)SET(P)3$ 
T=>POINTER = P3 
GO TO 
L$ 
END_AREA_OPEN2: 
END 
AREA_OPEN23 


Figure 3.2 Linking components 


ZDECLARE LIST_COMPONENT CHARACTER; 
ZLIST_COMPONENT = *°1 COMPONENT 
BASED(P), 
2 DATA CHARACTER(1)> 
2 POINTER POINTER® $ 
AREA_OPEN3: 
PROCEDURE (AREA3,LIST)5 
DECLARE 
AREA3 AREA(*#), 


(LIST, T) POINTER, 
LIST COMPONENT $ 
ON AREA 
BEGINS 
IF 
PazNULL 
THEN 
P->POINTER = NULLS 
GO TO 
END_AREA_OPENS33 
END; 
P = NULL3 
ALLOCATE COMPONENT IN(AREA3) SET (PDS 
LIST = P3 
Ls 
T = P$ 


ALLOCATE COMPONENT IN(AREA3) SET(P)3 
T->POINTER = P35 
GO TO 


Ls; 
END_AREA_OPEN3: 
ENO 

AREA_OPEN3$ 


Figure 3.3. Using compile-time statements to specify the structure 
of list components 


A possible organization for this type of list head ap- 
pears in the structure declaration: 


1 LIST, 
2 SIZE FIXED DECIMAL(5), 
2 BODY POINTER 


The identifier LIST serves as the name of the list, and the 
pointer BODY specifies the address of the first component 
in the body of the list. The value of SIZE represents the 
number of components in the list. For an empty list, 
BODY is null, and SIZE has a zero value. 

The DELETE _ND subroutine in Figure 3.4A provides 
an example of a procedure that processes data lists with 
this type of head. The subroutine is similar to the pro- 
cedure given in Figure 2.12B, except that the head of the 
list being processed is a data structure and not a pointer 
element. When a data item is deleted, the size value in the 
list head is decreased by one. Similarly, because the de- 
leted component is inserted into the list of available stor- 
age components, AVAIL, the size value in the head of 
AVAIL is increased by one. Figure 3.4B contains examples 
of references to DELETE ND. 

Observe that DELETE ND uses two other list- 
processing procedures: ADDRESS _N2 and 
SET POINTER. ADDRESS _N2 (Figure 3.4C) resembles 
the ADDRESS_N procedure in Chapter 2. The two ver- 
sions cannot be the same, however, because they process 
lists with different types of heads. The same 
SET POINTER routine is used, since it is not concerned 
with list heads and assumes similar organizations for list 
components. 

The organization of a list head can be as complicated as 
desired so that a wide variety of information can be stored 
in the head, such as: 

1. Maximum size achieved by the list 

2. Number of references made to the list 

3. Name of the list (for output identification) 

4. Who has access to the list 

5. When the list was last processed 


In many respects, an expanded list head resembles the 
label record used for identification and protection pur- 
poses at the front of many data files. The one essential 
item that the list head must contain, however, is the ad- 
dress of the first list component. 
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DELETE_ND2: 
PROCEDURE (LIST_HEAD »N)3 
DECLARE 
N FIXED DECIMAL(5), 
(ADORESS1» ADORESS2, ADORESS3) 
POINTER, 
1 LIST_HEAD, 
2 SIZE FIXED OECIMAL(5), 
2 BODY POINTER, | 
1 AVAIL_HEAD EXTERNAL, 
2 SIZE FIXED OECIMAL(5), 
2 BODY POINTER? | 
/* IF LIST_HEAD IS EMPTY OR N IS 
LESS THAN 1, THEN RETURN. */ 
IF 
(LIST_HEAD.SIZE = 0) | (NCL) 
THEN 
RETURNS 
/* DELETE FIRST COMPONENT WHEN 
N2=z=1. */ 
IF 
: N= 1 Ls 
THEN 
00; 
ADORESS2 = LIST_HEAO.B00Y;3 
LIST_HEAD.BODY = ADORESS_N2 
(LIST ~HEADs2)5 
GO TO 
L$ 


ENO; 


END 


/* OBTAIN ADDRESS OF N-TH 
COMPONENT. */ 
ADDRESS2 = ADDRESS_N2(LIST _HEADOND3 
IF 

ADDRESS2 = NULL 

THEN 
RETURNS 
ADDRESS1 = ADDRESS_N2 
(LIST_HEAD, N — 1)$ 
ADDRESS3 = ADDRESS_N2 
(LIST_LHEAD, N + 1)3 
/* DELETE N-TH COMPONENT AND 
DECREASE LIST_HEAD.SIZE BY le #/ 
CALL SET_POINTER(ADDRESS1, 
ADDRESS3)3 
LIST_HEAD.SIZE = LIST_HEAD.SIZE - 13 
/* INSERT DELETED COMPONENT INTO 
LIST OF AVAILABLE STORAGE 
COMPONENTS AND INCREASE 
AVAIL_HEAD_SIZE BY 1. */ 


ADDRESS1 = AVAIL_HEAD.BODY; 
AVAIL_HEAD.BODY = ADDRESS23 

CALL SET_POINTER(AVAIL_HEAD.BODY, 
ADDRESS1)3 
AVAIL_HEAD.SIZE = AVAIL_HEAD.SIZE+413 


DELETE_ND2; 


Figure 3.4A. Deleting the data item in the nth position of a data list, the size of which is stored in the list head 


Reference 


Data List 
| (before reference) 


| 00003 | FPA; Fs} Pec h\ 


ro000t | Pof =X 
00000 |\| 
us [00008 | HoH EL HI 


Figure 3.4B. Examples showing how size values in list heads are changed when data items are deleted 


ADDRESS_N2:PROCEDURE(LIST_HEAD, N) 
RETURNS (POINTER)$ 

DECLARE 
LIST_HEAD, 
SIZE FIXED DECIMAL(5), 
BODY POINTER, 
FIXED DECIMAL(5), 
COMPONENT BASED(C ADDRESS), 
DATA CHARACTER(1), | 
POINTER POINTER} 


NN & SNK = 


IF 


(LIST_HEAD.SIZE = 0) | (N < 1) 


Subroutine 


DELETE _ND(L1,2) | L1: 
DELETE_ND(L2,1) 
DELETE _ND(L3,1) 


DELETE _ND(L4,4) | L4: 


reeo02 | PolAL HEN 
roso00 
[e600 JX 


[0060s NeXT po 





THEN 
RETURN (NULL)$ 
| ADORESS = LIST_HEAD.BODY; 
dO 
I = 1 BY 13 
IF 
(ADDRESS->POINTER#NULL) &(I~2N) 
| THEN RETURN (NULL) 3 
IF 
I= N 
THEN RETURN( ADDRESS) 3 
ADDRESS = ADDRESS->POINTER$ 
END3 


END ADDRESS_N23 


Figure 3.4C. Obtaining the address of the nth component in a list, as used by DELETE_ND2 
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ALTERNATIVE METHODS FOR LINKING LIST 
COMPONENTS 


Using more than one pointer element in each list com- 
ponent permits the components to possess a more complex 
ordering than the simple linear ordering developed so far. 
The following discussions show how additional pointer 
elements may be used to create three general categories of 
lists with complex orderings: 

1. Two-way lists 

2. Circular lists 

3. Multidirectional lists 


Two-Way Lists 


The components of a two-way list are linked in both a 
forward and a backward direction, as illustrated by Figure 
3.5A. Each component contains two pointer elements: one 
for forward linking and the other for backward linking. 
The forward pointer contains the address of the next com- 
ponent in the list; the backward pointer contains the ad- 
dress of the previous component. The forward pointer of 
the last component and the backward pointer of the first 
component both contain null address values. 

Although the pointers in the diagram of Figure 3.5A 
point to other pointer elements, it should be understood 
that the pointers always contain the addresses of entire list 
components and not the addresses of elements within the 
components. 

This point is further illustrated by the subroutine pro- 
cedure FORM TWO_WAY in Figure 3.5B, which forms 
the two-way list shown in Figure 3.5A. As a simplification, 


Component Declaration 


1 COMPONENT 2W BASED(P), FORWARD: 
2 FORWARD_POINTER POINTER, 
2 DATA CHARACTER(1), 
2 BACKWARD_ POINTER POINTER BACKWARD: 





Figure 3.5A. Example of a two-way data list 


the procedure uses a storage area having external scope and 
assumes that the area contains sufficient storage for an- 
other list. 

With appropriate modifications, the techniques de- 
veloped in Chapter 2 can also be applied to this type of 
list. 

The major advantage of a two-way list is that it permits 
scanning operations to be performed with equal efficiency 
in both a forward and a backward direction. In many list- 
processing applications, it is necessary to stop at a certain 
position in a list and to process earlier portions of the list. 
To reach the earlier portions in a one-way list, a procedure 
must scan through the list from the beginning. Such scan- 
ning increases program running time, particularly when the 
portions being sought are not at the front of the list. Ina 
two-way list, the desired position can be reached by back- 
ing through the list. 

For example, in a text-editing program that uses list- 
processing techniques, it might be necessary to delete the 
first sentence of all paragraphs that end with a specified 
word. Such a program would scan to the end of each para- 
graph before determining whether the first sentence was to 
be deleted. With the text arranged in a two-way list, it 
would generally be more efficient to move backwards from 
the end of a paragraph than to come through the entire 
text to the beginning of the paragraph. 

Similar considerations apply to arithmetic expressions 
that contain nested subexpressions. Scanning such expres- 
sions by list-processing techniques generally requires fre- 
quent repositioning in forward and backward directions as 
subexpressions are processed. 


Example of Data List 
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FORM_TWO_WAY: | 
PROCEDURE (FORWARD, BACKWARD) $ 
DECLARE 
AREA2W AREA EXTERNAL,» 
(FORWARD, BACKWARD,T) POINTER, 
TABLE(6) CHARACTER(1) 
INITIAL PAS, "BY, *C%, "D8, *E%, 
Fe), 
1 COMPONENT2W BASED(P), 
2 FORWARD_POINTER POINTER, 
2 DATA CHARACTER(1), 
2 BACKWARD_POINTER POINTERS 
/* ALLOCATE FIRST LIST COMPONENT, 
AND LINK IT TO LIST HEAD. */ 
ALLOCATE COMPONENT 2W 
IN (AREA2W) SET(P)$ 
FORWARD = P3; 
P—>DATA = TABLE(1)3 — 
P-=>BACKWARD_POINTER = NULL3 
/* ALLOCATE REMAINING FIVE 
COMPONENTS, ANO LINK ALL COMPONENTS 
IN FORWARD AND BACKWARD OIRECTION. */ 
dO 
I = 2 TO 63 
T = P$ 
ALLOCATE COMPONENT 2W 
IN (AREA2W) SET(P)$ 
T—->FORWARD_POINTER = P35 
P—=>DATA = TABLE(I)$ 
P-=>BACKWARD_POINTER = T3 
END; 
P—>FORWARO_POINTER = NULLS 
BACKWARD = P; 
ENO 
FORM_TWO_WAY; 


Figure 3.5B. Forming a two-way list 


Circular Lists 


A circular list is obtained by linking the last component of 
a one-way list to the first component. Similar linking, 
when applied to a two-way list, produces a two-way circu- 
lar list, as shown in Figure 3.6A. 

Subroutine procedure FORM TWO_WAY _ CIR- 
CULAR in Figure 3.6B forms the two-way circular list 
illustrated in Figure 3.6A. The subroutine uses an external 
storage area, which is assumed to contain enough free 
storage for another list. When the list is formed, it is linked 
to the list head specified in the invocation of the subrou- 
tine. 

Circular lists prove useful in applications that perform 
repeated processing of list items. In a time-sharing system, 
for example, each component of a list may contain control 
information for a remote terminal that is requesting com- 
puter time. Since each terminal receives service for brief 
periods so that no terminal is forced to remain idle very 
long, repeated servicing of the terminals is required until 
each has completed its task. When a terminal becomes 
inactive, its corresponding component is deleted from the 
circular list. Reactivation of a terminal reinserts the as- 
sociated component into the list. 

Graphic display devices provide another application of 
circular lists. Any data that is displayed on a graphic con- 
sole must be transmitted continually; otherwise, it will 
fade from the display screen. Placing the display data in a 
circular list provides a convenient way of repeatedly re- 
trieving and displaying the data until an interrupt condi- 
tion terminates the display. 


Two-way circular list 





Figure 3.6A. Examples of circular lists 
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FORM_TWO_WAY_CIRCULAR:? 

PROCEDURE (L2)3 
DECLARE 

AREAC AREA EXTERNAL, 
(L2_5 T) POINTER, 
TABLE(4) CHARACTER(1) 
INITIAL C8 Ws OXF, 8 VF, P29 De 
1 COMPONENTC BASED(P), 
2 FORWARD_POINTER POINTER, 
2 DATA CHARACTER(1), 
2 BACKWARD_POINTER POINTER? 
4* ALLOCATE FIRST LIST COMPONENT, 
AND LINK IT TO LIST HEAD. */ 
ALLOCATE COMPONENTC INC AREAC)SET(P)$ 
L2 = P$ 
P->DATA = TABLE(1)$ 
/* ALLOCATE REMAINING THREE 
COMPONENTS, AND LINK ALL COMPONENTS 
IN FORWARD AND BACKWARD 
OIRECTION. */ 


DO 

I= 2 T0 43 
T = P$ 
ALLOCATE COMPONENTC INCAREAC)SET(P)$ 
T->FORWARD_POINTER = P35 
P—>DATA = TABLE(I)3 
P—=>BACKWARD_POINTER = T3 

END; 
/* COMPLETE FORWARD AND BACKWARD 
CIRCULAR LINKS. */ 
P—>FORWARD_POINTER = L23 
L2->BACKWARD_POINTER = P3¢ 

END 


FORM TWO WAY CIRCULARS 


Figure 3.6B. Forming a two-way circular list 


Component Declaration 


1 COMPONENTH BASED(P), 
2 FORWARD_ POINTER POINTER, 
2 DATA CHARACTER (1), 
2 HEAD POINTER POINTER 


Circular lists also permit more accurate modeling of 
data organizations that contain inherent circularities. Later 
discussions present illustrations of such organizations in 
chemistry, geometry, and the game of chess. 

Note that the circular lists presented in Figure 3.6A do 
not include the list head as part of the circular linkage. As 
Figure 3.7A shows, however, the list head can be included 
in the circular linkage. Each component contains a second 
pointer element that points to the list head. This organiza- 
tion provides each component with quick access to the list 
head. 

An application for this type of list involves the light pen 
on a graphic display device. The light pen can be used to 
refer to a portion of the data on the display screen. If the 
display data is stored within the computer in list form, the 
effect of the light pen is equivalent to selecting a list com- 
ponent without first determining what list contains the 
component. Storing the address of the list head within 
each component identifies the containing list immediately. 

Subroutine procedure FORM CIRCU- 
LAR_TO_HEAD in Figure 3.7B shows how to create the 
list shown in Figure 3.7A. Observe that this list is actually 
a two-way circular list. The forward linkage does not in- 
clude the list head, but the backward linkage does. 


Example of Data List 





Figure 3.7A. Circular list with additional pointer elements that point to the list head 


FORM_CIRCULAR_TO_HEAD: 
PROCEDURE (L1)3 

DECLARE 
AREAH AREA EXTERNAL, 
(L1,ADDRESS_OF_HEAD, T) POINTER, 
TABLE(5) CHARACTER(1) 
INITIAL(* 1%, 82%, 83%, "48, "58D, 
1 COMPONENTH BASED(P), 
2 FORWARD_POINTER POINTER, 
2 DATA CHARACTER(1), 
2 HEAD_POINTER POINTER; 
/* OBTAIN ADDRESS OF LIST HEAD. */ 
ADDRESS_OF_HEAD = ADDR(L1)3 
/* ALLOCATE AND LINK FIRST LIST 
COMPONENT. #/ 


ALLOCATE COMPONENTH INC AREAH)SET(P)$ 


Ll = P3 


P—>DATA = TABLE(1)5 

P—>HEAD_POINTER = ADDORESS_OF_HEAD; 
/* ALLOCATE AND LINK REMAINING FOUR 
COMPONENTS. */ 


DO 

I= 2 T0 53 
T = P3 
ALLOCATE COMPONENTH INCAREAH)DSET(P)S 
T=>FORWARO_POINTER = P35 
P->DATA = TABLE(TI)$ 
P=>HEAD_POINTER = ADDRESS_OF_HEAD; 

END; 
/* COMPLETE FORWARD LINK. */ 
P->FORWARO_POINTER = L138 

END 


FORM_CIRCULAR_TO_HEAD$ 


Figure 3.7B. Forming a circular list with additional pointer elements that point to the list head 
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Multidirectional Lists 


When more than one pointer element is permitted in each 
list component, it is possible for each component to pos- 
sess more than one immediate predecessor component and 
more than one immediate successor component. The 
multidirectional organization of data lists with such com- 
ponents serves as a convenient tool for modeling complex 
systems that possess discrete arrangements of their parts. 
Examples of such systems occur in many fields: 


Electrical and communication networks 
Industrial-process scheduling 

PERT and critical path analyses 

Economic and social structures 

Military tactics and logistics 

Switching circuits 

Chemical structures 

Optimization of transportation routes and network 
flows 

Games and puzzles 


The general subject of graph theory provides a mathe- 
- matical foundation for the study of these systems. This 
theory uses circles (or points) interconnected by lines to 
represent the essential organization of a system. In a high- 
way network, for example, the lines of a graph may repre- 
sent roads, and circles may denote the points where the 
roads intersect. | 
‘When it is possible to trace a path through a graph and 
return to a previously encountered circle, the graph is said 
to contain a circuit. A graph without circuits is called a 
tree. Examples of both types of graphs appear in Figure 
3.8. | 

A special case of a tree graph occurs when each circle 
has at most two immediate successor circles. Such a graph 
is called a binary tree. Figure 3.9A shows how a binary 
tree may be used to represent a mathematical expression in 
parentheses -- free form. The figure also contains a repre- 
sentation of the binary tree as a data list. Each component 
in the list contains a left pointer and a right pointer, which 
provide the two possible branches from the component. 
This type of list forms a useful feature in many compila- 
tion techniques. 

The subroutine procedure FORM BINARY _ TREE in 
Figure 3.9B shows how to construct the data list presented 
in Figure 3.9A. In common with the three remaining illus- 
trations of specialized data lists in this chapter, processing 
of FORM BINARY _ TREE has been limited to compila- 
tion and execution. 
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ADVANCED APPLICATIONS OF COMPLEX DATA 
LISTS 


As indicated in the discussion of multidimensional lists, 
the range of possible applications for complex data lists is 
extensive and easily exceeds the scope of this text. The 
following discussions, therefore, deal with only three ap- 
plication areas: chemistry, geometry, and the game of 
chess. Since each of these areas is in turn quite broad, no 
attempt is made to develop complete applications. The 
intent of the discussions is to outline some of the ways 
complex list organizations may be used in advanced ap- 
plications. | 


List Representation of Structural Formulas in Chemistry 


Chemistry deals with the structure of matter and its 
changes and uses two types of formulas to describe the 
atomic structure of substances: empirical formulas and 
structural formulas. Examples of empirical formulas for 
common substances are: 


H,O ~— -- Water 
CO, -- Carbon Dioxide 
NaCl _— -- Sodium Chloride (salt) 


H,SO, -- Sulfuric acid 


Single or double letters specify atoms: H (hydrogen), O 
(oxygen), C (carbon), Na (sodium), Cl (chlorine), and S 
(sulfur). Subscripts indicate the number of atoms in a 
molecule (the smallest amount) of a substance. A single 
atom employs no subscript. Therefore, the formula H,O 
states that a molecule of water contains two hydrogen 
atoms (H,) and one oxygen atom (QO). 

The formula HO also indicates that an oxygen atom 
has two possible “‘places of attachment” with other atoms 
and that a hydrogen atom has only one place of attach- 
ment. In structural formulas these places of attachment are 
made visible by lines, called bonds, which are attached to 
the letter symbol for each atom. 

The top row of Figure 3.10 contains the structural 
formulas for hydrogen (one bond), oxygen (two bonds), 
nitrogen (three bonds), and carbon (four bonds). Other 
atoms have larger numbers of bonds; the maximum is 
seven. 


* 
— Ny yO 





A graph with circuits 


A graph without circuits (a tree) 


Figure 3.8. Examples of graphs 


97 


Expression: A — (B*((C/D) + (E/F))) | 





Expression as a binary tree 


| | (Drees ee. ee Ae ee ee 7 
L: Ro , | 1 COMPONENTBT BASED(P), | 

| 2LEFT_ POINTER POINTER, | 

| 2 DATA CHARACTERI1), , 

| 2RIGHT_POINTERPOINTER , 


Expression as a data list 


Figure 3.9A. Representation of a binary tree as a data list 
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FORM_BINARY_TREE? 


PROCEDURE (L)$ 


AREA6 AREA EXTERNAL, 

tL POINTER, 

(P, Q, ReS) POINTER, 

1 COMPONENTBY BASED(P), 

2 LEFT_POINTER POINTER, 

2 DATA CHARACTER(1), 

2 RIGHT_POINTER POINTERS 

/* FORM E/F. */ 

ALLOCATE COMPONENTBT IN(AREAG)SET(P)$ 
ALLOCATE COMPONENTBT IN(AREA6)SET(Q)$ 
P=>LEFT_POINTER = NULL3 

P=>DATA = *E*$ 

P=>RIGHT_POINTER = NULL3 
Q->LEFT_POINTER = NULL3 

Q->DATA = *F*¢ 

Q—->RIGHT_POINTER = NULL3 

ALLOCATE COMPONENTBT IN(AREA6)SET(R)$ 
R->LEFT_POINTER = P35 

R=>DATA = */*$5 

R=>RIGHT_POINTER = Q3 

/* FORM C/D. */ 

ALLOCATE COMPONENTBT IN(AREA6)SET(P)3$ 
P=>LEFT_POINTER = NULLS 

P—=>DATA = "Cf; 

P->RIGHT_POINTER = NULL3$ 

ALLOCATE COMPONENTBT IN(AREA6)SET(Q)3 
Q—->LEFT_POINTER = NULLS ENO 
Q—>DATA = "D°35 


Figure 3.9B. Forming a binary tree as a data list 


Q->RIGHT_POINTER = NULL35 

ALLOCATE COMPONENTBT IN(AREA6)SET(S)5 
S->LEFT_POINTER = P; 

S->DATA = */'*5 

S->RIGHT_POINTER = Q5 

4* FORM (C/D) + (E/F). */ 

ALLOCATE COMPONENTBT IN(AREA6)SET(P)S 
P=>LEFT_POINTER = S35 

P—>DATA = *#*5 

P—->RIGHT_POINTER = R35 

/* FORM B¥((C/D0) + (E/FI). */ 
ALLOCATE COMPONENTBT IN(AREA6)SET(Q)$ 
Q->LEFT_POINTER = NULL; 

Q->DATA = "Bf; 

Q—->RIGHT_POINTER = NULL3$ 

ALLOCATE COMPONENTBT IN(AREAS)SET(R)$ 
R->LEFT_POINTER = Q5 

R=>DATA = *%**;5 

R->RIGHT_POINTER = P35 

/* FORM A-(B*¥((C/D) + (CE/FII). */ 
ALLOCATE COMPONENTBT IN(AREA6)SET(Q)$ 
Q—>LEFT_POINTER = NULL; 

Q—->DATA = *A®S 

Q=->RIGHT_POINTER = NULL3$ 

ALLOCATE COMPONENTBT IN(AREA6)SET(P)$ 
P=>LEFT_POINTER = Q3 

P=>DATA = *=85 

P->RIGHT_POINTER = R35 

L = Ps 


FORM_BINARY_TREES$ 
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Hydrogen atom 





Oxygen atom Nitrogen atom 


CH4: Methane 


CgH1g: Normal octane 


CgHig: Isooctane CgHg: Benzene ring 





Figure 3.10. Examples of structural formulas in chemistry 


The structural formulas in the remaining rows of Figure 
3.10 show how atoms are joined by their bonds to form a 
variety of substances: molecular oxygen (in the air we 
breathe), carbon dioxide (formed during respiration), 
ammonia (the gas contained in household cleaners), 
methane (natural gas used for fuel), normal octane (used in 
gasoline), isooctane (used in high-octane gasoline), and 
benzene (a coal-tar derivative used as a solvent). 

Structural formulas prove to be of great importance to 
chemists, because they not only specify the type and num- 
ber of atoms but also show how the atoms are arranged 
and interconnected within a molecule of a substance. Al- 
though two molecules may contain the same type and 
number of atoms, the atoms may be arranged differently 
and, as a result, form different substances. For example, 
Figure 3.10 shows how 8 carbon and 18 hydrogen atoms 
may be combined to form two different molecules: normal 
octane and isooctane. Both molecules possess the same 
empirical formula, Cg H, g, but are actually different sub- 
stances. 

Data lists provide a convenient way of representing the 
structural organizations of molecules. Figure 3.11A con- 
tains a list representation for the structural formula of 
water (H—O—H). Each list component represents an atom 
and contains a two-position character string for the letter 
symbol of the atom and seven pointer elements, which 
serve as connecting bonds. When an atom has fewer than 
seven bonds, unused pointers are set to null. 


Structural Formula 
for Water 


WATER: 


| 1 ATOM BASED(P), 
2 SYMBOL CHARACTER (2), : 
| 2 BOND(7) POINTER 


Figure 3.11A. List representation of water 


Subroutine procedure FORM WATER in Figure 3.11B 
shows a way of creating the data list in Figure 3.11A. 

Once the structural formula for a molecule is repre- 
sented as a data list, a variety of procedures can be written 
to analyze the structure of the molecule, to search for 
patterns of atoms, and to simulate chemical experiments. 


List Representation of Geometric Figures 


The use of data lists to represent the geometric arrange- 
ment of atoms in molecules indicates that data lists may 
also be used to represent the structure of geometric figures 
in general. 

Figure 3.12A shows declarations for the head and com- 
ponents of a data list that represents a pyramid. Besides 
containing the address of the first list component, the list 
head includes the name and volume of the pyramid. Each 
list component represents a vertex in the figure and con- 
tains the name and the three coordinates of the vertex. Six 
pointer elements also appear in each list component: one 
pointer links the component to its successor component, 
and the remaining five pointers each link the component 
to other components that form each of the five possible 
faces in the pyramid. If a vertex is not associated with a 
particular face in the pyramid, the corresponding pointer is 
null. 


List Representation of Structural Formula 


for Water 
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FORM_WATER? - ALLOCATE ATOM IN(AREA7T) SET(Q)3_ 


PROCEDURE (WATER) S$ | , | Q=>SYMBOL = °H®s 

DECLARE | 7* LINK SECOND HYDROGEN ATOM TO 
(WATER »P,Q) POINTER, OXYGEN ATOM. */ 
AREAT AREA EXTERNAL, Q—>BOND(1) = P35 
1 ATOM BASEOD(P), | : P->BOND(2) = Q3 
2 SYMBOL CHARACTER( 2), /* IN EACH ATOM, SET UNUSED BONDS 
2 BOND(7) POINTERS TO NULL */ 
/* FORM FIRST HYOROGEN ATOM ANDO 00 
LINK IT TO POINTER CALLED WATER. #/ | I = 2 TO 73 WATER=>BONDO(I) = NULL3 
ALLOCATE ATOM IN(AREA7) . SET(WATER DS END; , 
WATER=>SYMBOL = °H*>5 DO | 7 
/* FORM OXYGEN ATOM. */ : I = 3 TO 73 P=->BOND(I) = NULL3 
ALLOCATE ATOM INCAREAT) SET(P)DS END; | | 
P->SYMBOL = *0°; DO | 
/* LINK HYDROGEN ANDO OXYGEN ATOMS.%/ — I = 2 TO 73 Q=>BOND(I) = NULL? 
WATER->BOND(1) = P35 END; 
P->BOND(1) = WATERS | END 
/* FORM SECOND HYDROGEN ATOM. #/ | FORM_WATER3 


Figure 3.11B. Forming the list representation of water 


A (1,1,3) 


(0,2,0) 





(0,0,0) 


1 LIST, VERTEX BASED(P), 

2 FIGURE POINTER, POINTER POINTER, 

2 FIGURE_NAME CHARACTER(10), VERTEX_NAME CHARACTER(1), 

2 VOLUME FIXED DECIMAL(3,1) X COORDINATE FIXED DECIMAL(1), 
Y_COORDINATE FIXED DECIMAL(1), 
Z COORDINATE FIXED DECIMAL(1), 
FACE ABC POINTER, 

FACE_ABE POINTER, 
FACE ACD POINTER, 
FACE _ADE POINTER, 
FACE_BCDE POINTER 


2 
2 
2 
2 
2 
2 
2 
2 
2 
2 





Figure 3.12A. Head and component descriptions for representing a pyramid as a data list 
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List: | | 
| 04.0 


ee aS 


Figure 3.12B. Representation of a pyramid as a data list 


Figure 3.12B shows the list representation of the pyra- 
mid in Figure 3.12A. Successive components for the entire 
pyramid are linked to form a one-way circular list. Succes- 
sive components for each face are also linked in circular 
fashion. As discussed earlier, circular lists simplify the 
continual display of data on a graphic device. 

Each vertex in the pyramid or in a face of the pyramid 
is obtained by moving through the associated circular list. 
By moving through the face pointers in a particular list 


k 
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component, it is possible to select each face that contains 
the associated vertex. 

Subroutine procedure FORM PYRAMID in Figure 
3.12C shows one way of constructing the data list in 
Figure 3.12B. 

Additional list-processing procedures can be designed to 
enlarge, contract, or change the orientation of a geometric 
figure on a graphic display device and also to create other 
figures by combining subfigures. 
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§OEM PYRAMIDS 
PROCEDURE (LIST, NAME, VOLUME, 
Kho Vio Zl oe X2eV29Z29X3eV30L38 
K49V4 9149 X59V5 92598 

DECLARE 
NAME CHARACTER(1ODs 
VOLUME FIXED DECIMAL(391)¢ 
(XL oe Vl go ZloeX2eV2elZZ2eX3eV3e7Z3e 


X49V49249X59V597Z5) FIXED DECIMAL(I), 


AREAQ AREA(5000) EXTERNAL, 
(AsBeCeDeE,y VI5)) POINTER, 

LIST, 

FIGURE POINTER, 

FIGURE_NAME CHARACTER(10), 
VOLUME FIXED DECIMAL(2)>¢ 
VERTEX BASED(P), 

POINTER POINTER, 

VERTEX_NAME CHARACTER(1), 
X_COORDINATE FIXED DECIMAL(C1), 
Y_COORDINATE FIXED DECIMAL(1), 
Z_COORODINATE FIXED DECIMAL(1), 
FACE_ABC POINTER, 

FACE_ABE POINTER, 

FACE_ACD POINTER, 

FACE_ADE POINTER, 

FACE_BCDE POINTERS; 

/* ALLOCATE STORAGE FOR FIVE 
VERTICES. #/ 


NNNN NN NADY A & — A A 


00 
I= 1 TO 53 | 
ALLOCATE VERTEX IN(AREAS)DSET(P)s 
VII) = Ps 
END; 


/* INITIALIZE LIST HEAD, ANO LINK 
VERTICES. #/ 

FIGURE_NAME = NAME; 

LIST.VOLUME = VOLUME; 

FIGURE = V(1)3 

A= V(LD3 B = W(2)s C = V«3D3 

D = V(4)3 E = V(5)5 


A->POINTER = B; 
B->POINTER = C35 
C->POINTER = D3 
D->POINTER = E3 


E->POINTER = A$ 

/* ASSIGN NAMES TO VERTICES. */ 
A~>VERTEX_NAME = *A®; 
B->VERTEX_NAME = *8°; 
C->VERTEX_NAME = *C*; 


Figure 3.12C. Forming the list representation of a pyramid 


List Representation of a Chessboard 


Various attempts have been made in the field of artificial 
intelligence to program a computer so that it can play a 
game of chess. Although no program has yet been able to 
master chess, modest success has been achieved by some 
programs in playing against human opponents, and the 
game still remains a fertile area for research on such topics 
as pattern recognition, heuristic methods, and machine 
learning. 

The following discussion shows how a data list can be 
used to represent a chessboard and how the chessmen can 
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D->VERTEX_NAME = °D?; 
E->VERTEX_NAME = *E?; 

/* ASSIGN COORDINATES TO 
VERTICES. */ 


A->X_COOROINATE = X13 
A->Y_COORDINATE = Yl; 
A->Z_COORDINATE = Z13 
B->X_COORDINATE = X23 
B->Y_COORDINATE = Y23 
B->Z_COORDINATE = 223 
C->X_COORDINATE = X33 
C->Y_COORDINATE = Y33 
C->Z_COORDINATE = 233 
D->X_COORDINATE = X43 
D->Y_COORDINATE = Y43 
D->Z_COORDINATE = 243 
E->X_COORDINATE = X53 
E->Y_COORDINATE = Y53 
E->Z_COORDINATE = 253 
/* LINK VERTICLES TO FORM FIVE 
FACES. */ 

A->FACE_ABC = B3 
B->FACE_ABC = C3 
C->FACE_ABC = A; 
A->FACE_ABE = B; 
B->FACE_ABE = €E3 
E->FACE_ABE = Aj 
A->FACE_ACD = C3 
C->FACE_ACD = D3; 
D->FACE_ACOD = Aj 
A->FACE_ADE = D0; 
D->FACE_ADE = E3 
E->FACE_ADE = A3 


B->FACE_BCOE = C3 

C->FACE_BCDE = D3 

D->FACE_BCDE = €E3 

E->FACE_BCDE = B;3 

/* SET UNUSED POINTERS TO NULL. */ 

A->FACE_BCDE, 

B->FACE_ACDO, 

B->FACE_ADE, 

C->FACE_ABE, 

C->FACE_ADE, 

O->FACE_ABC, 

O->FACE_ABE, 

E->FACE_ABC, 

E->FACE_ACD = NULLS 
END ; 
FORM_PYRAMIDS 


be arranged on the board in initial position. No attempt is 
made at developing a program that actually plays chess; 


such a program lies beyond the scope of this text. 


Figure 3.13A contains an illustration of a chessboard 
and shows the chessmen for white and black arranged in 
initial position. Two-letter abbreviations represent the 
chessmen: WP (white pawn), WR (white rook), WN (white 
knight), WB (white bishop), WQ (white queen), and WK 
(white king). Substituting B for W provides similar ab- 
breviations for the black chessmen. 






Black 
+ [foe [am [ooo 
aoooooood 
ETT 
“COT 
CO 
2s 
acicacacs 
acca 





White 


Figure 3.13A. Chessboard in initial position, showing the 
coordinate system for identifying files and ranks 


Component Declaration 


1 SQUARE BASED(P), 

2 NAME CHARACTER (2), 

2 MAN CHARACTER(2), 
2 NEIGHBORING SQUARES, 

3 UP POINTER, 

DOWN POINTER, 

LEFT POINTER, 

RIGHT POINTER, 


R_DOWN POINTER, 
L_ UP POINTER, 


3 
3 
3 
3 R_UP POINTER, 
3 
3 
3 L_DOWN POINTER, 





The coordinate system is used for identifying individual 
squares on the board. The letters a through h specify files 
(columns), and the digits 1 through 8 specify ranks (rows). 
The identifier al, for example, represents the lower left- 
hand square, and the identifier h8 represents the upper 
right-hand square. 

Figure 3.13B shows a possible declaration for list com- 
ponents that represent squares on the board. The com- 
ponent contains the name of the square (its coordinate) 
and the name of the chessman on the square (a blank name 
indicates an empty square). The component also contains 
eight pointer elements that represent the eight possible 
directions to neighboring squares (as illustrated on the 
right of Figure 3.13B). 

Figure 3.13C shows the list representation for the chess- 
board. This illustration differs from the list representations 
used earlier. Double-arrowed lines specify two-way linking 
of squares, and the component elements for the names of 
the squares are not shown. These modifications of earlier 
conventions avoid a cluttered diagram. 

The list head (BOARD) points to square Al. Observe 
also that the list is essentially a circular list with many 
circuits. 

The procedure named CHESS in Figure 3.13D contains 
the subroutines named BUILD BOARD and SET_ MEN. 
The subroutine procedure BUILD _ BOARD shows how to 
construct the list in Figure 3.13C. Subroutine procedure 
SET MEN sets the chessmen on the board in initial posi- 
tion. Neither subroutine uses parameters; external variables 
provide the necessary communication with the sub- 
routines. 


A Square Linked 
to Neighboring Squares 


a 


Figure 3.13B. Possible directions from a chessboard square to neighboring squares 
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CHESSsPROCEDURE OPTIONS( MAIN) 3 


CALL BUILO_BOARD3 
BUILD_ BOARD: 


PROCEDURE 3 


DECLARE 


DO 


DO 


END; 
END; 


DO 


DO 


END; 
END; 


DO 


ENO: 


DO 


DO 


Figure 3.13D. Building a chessboard and setting chessmen on the board (Continued) 


AREAQ AREA (5000), 

1 SQUARE BASED(P), 

2 NAME CHARACTER(2),¢ 

2 MAN CHARACTER(2), 

2 NEITGHBORING_SQUARES, 
3(UP, OOWN,LEFT, RIGHT, 
R_UP »R_DOWN»L_UP»L_OOWN, POINTER) 
POINTER, 
(S,FILE(8),RANK(8) »- BOARD, 
Al,»A29A3—¢A4,A5, Ab, AT AB, 
61,827B3»,B4sB85,86,B7,B8, 
C1,C29C39C%4eC54C6,C7 C8, 
01,02,03,04,05,06,07,08, 
El,E29E3 9 E49E5 7 EG, ETIESB, 
Fl,F2eF3—F4eF5eF6,FT, FE, 
G1sG22639649G65_566,G67,G68, 
H1,H29H3.H4eH5 »Hb6,H7T,HS ) 
EXTERNAL POINTER; 

4* FORM 8 BOARD FILES WITH 
NEIGHBORING SQUARES CONNECTED BY 
UP_POINTERS. */ 


I = 1 TO 83 
S = NULL3 


J = 1 TO 83 

ALLOCATE SQUARE IN (AREAO) SET (P)5 
P=>UP = S; 

S = P$ 


FILE(I) = S3 


/* USE DOWN_POINTERS TO CONNECT 
NEIGHBORING SQUARES. */ 


1 TO 83 
FILECI)$ 
NULL $ 


“nT 
H of of 


J = 1 70 83 
P—>DOWN = S3 
S = P3 

P = P—>UP;3 


/* INITIALIZE RANK_POINTERS. %/ 
P = FILE(1)$ 


I= 1 TO 83 
RANK(I) = P3 


P = P—>UP; 


/* USE RIGHT_POINTERS TO CONNECT 
NEIGHBORING SQUARES. */ 


1 TO 73 
FILECI)$ 
FILE(T + 1)3 


@ OTN = 


= 1 TO 83 
S->RIGHT = P3 
S = S=>UP; 

P = P->UP; 


END; 
END; 


DO 


END; 


DO 


DO 


END3 
END3 


DO 


00 


END3 
END3 
00 


END; 


DO 


DO 


END3 
END; 


DO 


END; 


DO 


P = FILE(8)$ 


I= 1 TO 83 
P=>RIGHT = NULL? 
P = P=>UP $5 


/* USE LEFT_POINTERS TO CONNECT 
NEIGHBORING SQUARES. */ 


I = 1 TO 83 
P = RANK(I)3 
S = NULL3 


J = 1 TO 83 
P->LEFT = S$ 
S = P3 

P = P=>RIGHT3 


/* USE RIGHT-UP-POINTERS TO CONNECT 
NEIGHBORING SQUARES. */ 


1 TO 73 
FILECI): 
FILECI + 1)3 
P=>UP 3 


CTUW 


J 2= 1 T0 73 
S->R_UP = P3 
S = S=>UP3 

P = P=>UP3 


S=>R_UP = NULL} 
S = FILE(8)3 


I = 1 TO 83 
S->R_UP = NULL? 
S = S=>UP3 


/* USE RIGHT-DOWN-POINTERS TO 
CONNECT NEIGHBORING SQUARES. *%/ 


I = 1 TO 73 

S = FILE(I)3 
S->R_DOWN = NULL? 
S = S=->UP3 

P= FILECI + 1)3 


J2=1 TO 73 
S->R_DOWN = P3 
S = S->UP3 
P = P=>UP 3 


S = FILE(8)$ 


I = 1 TO 83 
S->R_DOWN = NULLS 
S = S->UP3 


/* USE LEFT-UP—POINTERS TO CONNECT 
NEIGHBORING SQUARES. */ 
S = FILE(1);$ 


I = 1 TO 83 


S->L_UP = NULL3 
S = S=<->UP$ 
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END 
DO 


DO 


ENO; 
ENDS; 


00 


ENO 
00 


dO 


END; 
END; 


DVAV - 
onen w 


1 TO 73 


FILE(I)$ 
S—->UP $ 
FILEC(I + 


1)$ 


J = 1 TO 73 
P=>L_UP = S$ 
P = P=>UP 3 

S = S=>UP3 


P->L_UP = NULL; 


/* USE LEFT-DOWN-POINTERS TO 


NEIGHBORING SQUARES. 


*/ 


S = FILE(1)$ 


I = 1 TO 83 
S->L_DOWN = NULL$ 
S = S=~>UP 3 


I = 1 TO 73 

S = FILE(I)3 

P = FILE(I + 1)3 
P->L_DOWN = NULL3$ 
P = P=>UP3 


Jz=il 


TO 73 


P—>L_DOWN = S3 


P = P=>UP 3 
S = S=>UP3 


CONNECT 


/*® ASSOCIATE INOIVIDUAL POINTERS 


_ WITH 


Al 
A3 
A5 
AT 
Bl 
B3 
BS” 
87 
Cl 
C3 
C5 
C7 
01 
D3 
05 
07 
El 
E3 
E5 
E7 
Fl 
F3 
F5 
FT 
Gl 
G3 
G5 
G7 
H1 
H3 
H5 
H7 


EACH SQUARE. */ 

FILE(1)$3 A2 = FILE(2)3 
FILE(3)3 AS = FILE(4)3 
FILE(5)$s A6 = FILE(6)$ 
FILE(7)3 AS = FILE(8)3 


Al->UP; B2 = A2->UP; 
A3—>UP$; B4 = A4->UP; 
A5—>UP3 B6 = A6->UP; 
A7—->UP; BB = A8->UP; 
B1->UP$; C2 = B2->UP; 
B6->UP3; C4 = B4->UP; 
B5—>UP; C6 = B6->UP; 
B7->UP; C8 = B8->UP; 
C1->UP3 02 = C2->UP3 
C3=>UP3 D4 = C4->UP3 
C5=>UP3 D6 = C6->UP; 
C7->UP3 D8 = C8->UP; 
D1->UP; E2 = D2->UP; 
D3->UP; E4 = D4->UP; 
D5=>UP; E6 = D6->UP; 
O7->UP3; E8 = D8->UP; 
El->UP3; F2 = E2->UP; 
E3->UP3 F4 = E4->UP; 
E5->UP3 F6 = E6->UP; 
E7->UP; F8 = E8->UP; 
F1->UP3 G2 = F2->UP; 
F3->UP3 G4 = F4->UP3; 
F5->UP3 G6 = F6->UP3 
F7->UP3; G8 = F8->UP; 
G1->UP3 H2 = G2->UP; 
G3->UP3 H4 = G4->UP3 
G5->UP3 H6 = G6->UP; 
G7->UP3 H8 = G8->UP; 


/* ASSOCIATE BOARD POINTER WITH Al 
POINTER. */ 
BOARD = Al3 


/* ASSIGN NAME TO NAME ELEMENT OF 
EACH SQUARE. */ 


Al->NAME = *A1l®3 A2=->NAME = *A2*3 
A3->NAME = "A3*3 AS->NAME = *A4S3 
A5~>NAME = "A5®$ A6->NAME = *A6%S 
AT->NAME = "AT*®3 AB—>NAME = *A8B'3 
BI1->NAME = *B1*3 B2->NAME = *B2°3 
B3->NAME = °B3"°3 B4->NAME = *B4'$ 
B5->NAME = °B5"3 B6->NAME = *B6'3 
B7->NAME = *B7°3 B8&->NAME = °B8°3 
CI->NAME = *C1*§ C2->NAME = 'C2°$ 
C3->NAME = °C3%3 C4->NAME = §C4%3 
C5->NAME = *C5"% 3 CO6->NAME = *C6%3 
CT->NAME = "C7*%3 CB->NAME = °C8°3 
DI->NAME = *D1°3 D2->NAME = *02°3 
D3->NAME = "03° 3 D4->NAME = *04%3 
D5->NAME = 'D5"3 D6->NAME = 'D6'3 
D7->NAME = *D7"3 D8->NAME = *08°3 
E1->NAME = "E1*3 E2->NAME = SE2*$ 
E3=>NAME = *E3*3 E4->NAME = °E4'3 
E5=->NAME = "E53 E6->NAME = %E6%3 
E7->NAME = *E7*%3 E8->NAME = °E8*$ 
FI-=>NAME = *FL"3 F2->NAME = *F2°3 
F3=>NAME = *F3"3 F4->NAME = °F493 
F5=>NAME = "F5%3 F6->NAME = "FESS 
FI->NAME = *F7*3 F8~>NAME = °F8*5 
G1->NAME = 'G1"3 G2->NAME = *G2'3 
G3->NAME = 'G3*3 G4->NAME = 'G4°5 
G5->NAME = "G5" 3 G6->NAME = 'G6%5 
G7->NAME = "G7"$3 G8->NAME = °G8°5 
H1->NAME = *H1"$3 H2->NAME = ‘H2'5 
H3->NAME = *H3*3 H4->NAME = 'H4'§ 
H5—->NAME = *H5*$ H6->NAME = *H6"$ 
H7->NAME = *H7"'s H8—>NAME = °H8*$ 


CALL SET_MEN; 


SET_MENS 


DECLARE 


DO 


PROCEDURE $ 


1 SQUARE BASED(P), 

2 NAME CHARACTER(2), 

2 MAN CHARACTER(2), 

2 NEIGHBORING_SQUARES,s 
3(UP »DOWN, LEFT »RIGHT,» 

R_UP,»R_DOWN,L_UP,L_DOWN) POINTER, 
(A19A29A39A%4%_,A5,A6yA7,A8,y 
B1,82,B83,84,85,86,87,B8, 
C19C29C39C4eC52C6yC7,C8, 

D1,02,03,04205,D6,07,08, 

El,E2eE3,E4,E5, EG, ET ZEB, 

Fl»F29F3,F4,F5,F6,F7,F8, 

G1962963564965,665G67 768, 

H1eH2 9H3,H4.H5 pH6eH7 HB, 


RANK(8)). EXTERNAL POINTERS 


/* ASSIGN MEN TO INITIAL 
POSITIONS. 


*/ 
A1l->MAN = "WR*5 


A2->MAN = 


A3->MAN = "WB*$ A4->MAN = 


AS->MAN = *WK*S 
AT->MAN = 


I= 1 TO 83 


A6->MAN = 


"WN®S AS8=>MAN = 
P = RANK(2)3 


P—=>MAN = °WP*S 
P = P=>RIGHTS 


Figure 3.13D. Building a chessboard and setting chessmen on the board (Continued) 
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Z 


CWNes 
"WQ*; 
"WB°s 
fWR®S 


ENO; 
DO 


END; 


00 


00 


END3 
END3 
END 


ENO 


P = RANK(7)3 


I = 1 TO 83 
P—>MAN = "BP* 
P = P=>RIGHTS 


HI1->MAN = °BR*$ H2->MAN ®@ *BN®3 
H3->MAN = "BBs H4->MAN = *8Q*3 
HS=—>MAN = "BK'$ H6—->MAN @ *BB'3 
HT<->MAN = "BN* 3 H8=->MAN = "BRE3 

/* BLANK MAN ELEMENTS OF REMAINING 
SQUARES. #/ 


I= 3 TO 63 
P = RANK(I)3 


J = 1 TO 83 
P<>MAN = & 03 
P = P=>RIGHT3 


SET_MEN3 


BUILD_BOARD3 


PUT SKIP LIST(*CHESS EXECUTED" )$ 
CLOSE FILE(SYSPRINT)3 
ENO CHESS} 


Figure 3.13D. Building a chessboard and setting chessmen on the 


board 


REVIEW OF COMPLEX DATA LISTS 


Chapter 3 shows how to create complex data lists by ex- 
tending the simple list organization of Chapter 2. These 
extensions involve using other types of data in list com- 
ponents besides single characters, storing descriptive in- 
formation about a list in the head of the list, and using 
additional pointer elements to obtain alternative orderings 
of list components besides a simple linear ordering. 

Illustrations of complex data lists appear in Figure 3.14. 
L1 is a two-way circular list of eight components. The 
head of the list contains a count of the components, and 
each component possesses two pointers: one for forward 
linking, the other for backward linking. The list of avail- 
able storage components, AVAIL, has 16 components. As 
illustrated, AVAIL need be linked in a forward direction 
only, because no intricate manipulations are performed on 
its components other than storing and retrieving available 
storage. 

Complex data lists prove useful in modeling intricate 
systems that possess discrete arrangements of their parts. 
Such systems occur in many areas: 


Electrical and communication networks 
Industrial-process scheduling 

PERT and critical path analyses 

Military tactics and logistics 

Switching circuits 

Chemical structures 

Optimization of transportation routes and network 
flows 

Games and puzzles 
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STORAGE_AREA 


Li: 


i! F tukcledkt 1 tore 


Figure 3.14. Complex data lists 


SUMMARY 


1. Chapter 3 shows how the simple list organization 
used in Chapter 2 can be modified to create more complex 
data lists. 

2. Modifications can include any or all of the essential 
elements of a simple data list: the head pointer, the com- 
ponent data item, and the component pointer. 

3. Descriptive information about the list, such as the 
size of the list and its name, may be stored in the head of 
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the list along with the head pointer. 

4. Each list component can contain data of any type 
and precision, including arrays, structures, and arrays of 
structures. 

5. Each list component can contain more than one 
pointer element, so that components may be linked in 
circular and multidirectional fashion. 


Appendix 1: Review of Facilities for Subroutines 
and Functions in PL/I 


This appendix reviews the main facilities for organizing 
and using subroutines and functions in PL/I. It deals with 
only those features that are used in this manual and does 
not attempt to cover all aspects of subroutines and func- 
tions. 


ORGANIZING SUBROUTINES 


A subroutine is a procedure block whose PROCEDURE 
statement has the form: 


entry-name: PROCEDURE [(parameter-1,parameter-2, 
. ,parameter-n)| ; 


The entry name is a statement label that serves as the name 
of the subroutine. Program control enters the subroutine 
through its entry name when the entry name is referred to 
in an invoking CALL statement. 

Each parameter in a PROCEDURE statement is a var- 
iable that is used within the subroutine and to which a 
value may be assigned by the CALL statement that invokes 
the subroutine. The parameters may also be used to return 
values to the procedure that contains the invoking CALL 
statement. Attributes for each parameter may be declared 
explicitly, implicitly, or contextually within the subrou- 
tine. It is also possible for the PROCEDURE statement in 
a subroutine to specify no parameters. 

When an invoking CALL statement sends control to a 
subroutine, the subroutine becomes active and remains 
active until control encounters either a RETURN state- 
ment or the final END statement of the subroutine. At 
that point, control returns to the statement immediately 
following the invoking CALL statement. 

When used in a subroutine, a RETURN statement has 
the form: 


RETURN; 


An arbitrary number of RETURN statements may appear 
in a subroutine. 


Example: 
SUM: PROCEDURE(VALUE1, VALUE2, TOTAL); 


DECLARE (VALUE1, VALUE2) FIXED 
DECIMAL(3), 


TOTAL FIXED DECIMAL(4); 
TOTAL = VALUE1 + VALUE2; 
RETURN; 


END SUM; 


The name of this subroutine is SUM, and it contains three 
parameters: VALUE1, VALUE2, and TOTAL. Parameters 
VALUE] and VALUE2 receive values when the subroutine 
is invoked. The subroutine then adds the values and assigns 
them to TOTAL. The value of TOTAL also becomes avail- 
able in the invoking procedure through an associated argu- 
ment variable. Execution of the RETURN statément sends 
control to the statement immediately following the in- 
voking statement. Had the RETURN statement been 
omitted in this example, the END statement would have 
returned control. 


USING SUBROUTINES 


Execution of a subroutine requires that it be invoked by a 
CALL statement, which has the form: 


CALL entry-name(argument-1 ,argument-2, . . .,argument-n); 


The entry name identifies the label attached to the PRO- 
CEDURE statement of the invoked subroutine. Each argu- 
ment can be a constant, a variable, or an expression, the 
value of which is automatically assigned to the corre- 
sponding parameter specified in the PROCEDURE state- 
ment of the subroutine. 
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Within the invoking procedure, explicit declaration of 
the entry name for a subroutine occurs with the ENTRY 
attribute, which has the form: 


ENTRY(parameter-attribute-list-1, . . ..parameter- 
attribute-list-n); 


Each parameter attribute list specifies the attributes of the 
corresponding parameter in the subroutine. The parameter 
attribute lists permit the invoking procedure to perform 
necessary conversions of argument values before they 
become associated with the corresponding parameter vari- 
ables. 


Example: 


T_SUBsPROCEOURF OPTIONS(MAIND$ 
DECLARE (A,B) FIXED DECIMAL(3), 
C FIXED DECIMAL(4), 
D0 CHARACTER(7T4), 
SUM ENTRY(FIXED DECIMAL(3), 
FIXEO DECIMAL (3), 
FIXED DECIMAL (4))3 
ON ENOFILE GO TO OVERS 
START: 
GET EDIT( A,B, 09 (F(3) F030, AC T4ID3 
CALL SUM(A,B,C)3 
PUT EDIT(AsB,CI(FI(6), FI6d, FITIDS 
PUT SKIP3 
GO TO START3 
SUMs PROCEDURE (VALUE]1, VALUE2, TOTAL); 
DECLARE(VALUE1, VALUE2) 
FIXED DECIMAL (3), 
TOTAL FIXED DECIMAL(4)3 
TOTAL = VALUE] # VALUE2$3 
RETURNS; 
END SUM$ 
OVER: 
END T_SUB3 


This example shows how subroutine SUM may be invoked 
from the main procedure T-SUB. The program gets a card 
from the standard system-input file, SYSIN, and assigns 
the integer in columns 1 through 3 to variable A and the 
integer in columns.4 through 6 to variable B. Invocation of 
subroutine SUM then occurs with the CALL statement: 


CALL SUM(A, B, C); 


Arguments A, B, C become associated with parameters 
VALUE1, VALUE2, and TOTAL in the subroutine. The 
values of VALUE1 and VALUE2 become identical with 
the values of A and B. When the sum of VALUE1 and 
VALUE2 is assigned to TOTAL, the value of argument C 
becomes identical with the value of TOTAL. 

Control returns from the subroutine to the PUT state- 
ment located immediately after the CALL statement. 
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T-SUB then prints the value of A, B, and C on a single line 
of the standard system-output file, SYSPRINT. These 
steps are repeated for each input card until the end of the 
SYSIN file is reached. 


ORGANIZING FUNCTIONS 


A function is a procedure block whose PROCEDURE 
statement has the form: 


entry-name: PROCEDURE(parameter- 1 ,parameter-2, 
.. parameter-n) RETURNS(result-attribute-list); 


This statement is similar to the PROCEDURE statement 
for subroutines except that it specifies the attributes of the 
value returned by the function. The result attribute list is 
optional; if it is not used, the attributes of the result are 
determined implicitly from the first letter of the function 
entry name (FIXED BINARY(15) for letters I through N 
and FLOAT DECIMAL(6) for all other alphabetic char- 
acters). 

A RETURN statement returns control from the func- 
tion and also specifies the result of the function: 


RETURN(element-expression); 


The expression, which can be a constant, a variable, or an 
operational expression, must be present and must specify a 
single value; it cannot represent an array or a structure 
value. A function can contain an arbitrary number of RE- 
TURN statements, each with a different element expres- 
sion: 


Example: 


MULT: PROCEDURE(VALUE1, VALUE2) RETURNS 
(FIXED DECIMAL(6)); 


DECLARE (VALUE1, VALUE2) FIXED 
DECIMAL(3); 


RETURN (VALUE]1 * VALUE2); 
END MULT; 


The function procedure MULT contains two parameters: 
VALUE] and VALUE2. These variables receive values 
when the function is invoked. The RETURN statement 
evaluates the product of VALUE1 and VALUE2 and re 
turns the result as the value of the function. The attributes 
of the result appear in the PROCEDURE statement as 
FIXED DECIMAL(6). 


USING FUNCTIONS 


A function is not invoked by a statement but by a func- 
tion reference, which has the form: 


entry-name(argument-1, argument-2, . . ..argument-n) 


A function reference can appear wherever an expression is 
permitted in PL/I, and the value of the reference is the 
result returned by the function procedure. When program 
control returns from the function procedure, it continues 
from the point of the invoking function reference. 
Each argument in a function reference can be a constant, a 
variable, or an expression (which itself may include a func- 
tion reference). The value of each argument is automati- 
cally assigned to the corresponding parameter specified in 
the PROCEDURE statement of the function. 

Explicit declaration of the entry name for a subroutine 
occurs with the ENTRY and RETURNS attributes, which 
have the form: 


ENTRY(parameter-attribute-list 1 , 
. .,.parameter-attribute-listn) 


RETURNS(result-attribute-list) 


Each parameter attribute list in the ENTRY attribute 
specifies the attributes of the corresponding parameter in 
the function. The result attribute list contains the attri- 
butes of the value returned by the function procedure. 


Example: 


T_FUNCTsPROCEDURE OPTIONS (MAIN) $ 
DECLARE (A,B)IFIXED DECIMAL(3), 
C FIXEO DECIMAL(6), 
O CHARACTER (74), 
MULT ENTRYCFIXED DECIMAL(3), 
FIXED ODECIMAL(3)) 
RETURNSCFIXED OECIMAL(6))3 
ON ENDOFILE GO TO OVERS 
START: 
GET EDIT(A,B,D) (F033) pF C3) pACTSIDS 
C = MULT(A,B)5 
PUT EDIT(AsBeCO(E(6)D, FCO), FI(9D)3 
PUT SKIP3$ 
GO TO STARTS | 
MULT>sPROCEDURE(VALUE], VALUE2) 
RETURNS (FIXED DECIMAL(6))3 
DECLARE( VALUE], VALUE2) 
FIXED DECIMAL(3)3 
RETURN (VALUE] ® VALUE2)3 
END MULT 
OVER: 
ENO T_FUNCT3 


This example shows how function MULT may be invoked 
from the main procedure T-FUNCT. The program gets a 
card from the standard system-input file SYSIN and as- 
signs the integer in columns 1 through 3 to variable A and 
the integer in columns 4 through 6 to variable B. Function. 
MULT is invoked by the reference MULT(A,B), which 
appears in the assignment statement: 


C = MULT(A,B); 


Arguments A and B become associated with parameters 
VALUE! and VALUE2 in the function procedure. 
VALUE! and VALUE2 receive the values of A and B, and 
the function returns the product of these values. The 
product is then assigned to variable C. 

The program prints the values of A, B, and C on a single 
line of the standard system-output file, SYSPRINT. These 
steps are repeated for each input card until the end of the 
SYSIN file is reached. 


DUMMY ARGUMENTS 


When an argument becomes associated with a parameter, 
the name of the argument, not its value, is passed to a 
subroutine or function. Some arguments, however, do not 
have names. For example, a constant has no name,-nor 
does an operational expression. These arguments, there- 
fore, cannot be associated directly with parameters. The 
compiler must provide storage for such arguments and 
create an internal name for each. These internal names are 
called dummy arguments. They are passed to the invoked 
subroutine or function in place of the original arguments 
that have no names. 

Dummy arguments cannot be addressed directly in 
PL/I. Any changes, however, in the values of their as- 
sociated parameters will be reflected in the dummy argu- 
ments, but the values of the original arguments will remain 
unchanged. 

The compiler creates a dummy argument when: 


1. An argument is a constant. 

2. An argument is an expression involving operators. 

3. An argument is enclosed in parentheses. 

4. An argument is a function reference. 

5. An argument is a variable whose data attributes are 
different from the data attributes declared for the as- 
sociated parameter in an ENTRY attribute within the 
invoking block. 


Changes to the value of a parameter will be reflected in the 
value of the original argument only if a dummy argument 
is not passed. When a dummy argument is not created, the 
argument name is passed directly to the invoked pro- 
cedure, and the associated parameter becomes identical 
with the argument. 
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If an ENTRY attribute is not used in an invoking block 
to describe the attributes of the parameters in the invoked 
procedure, the compiler assumes that the arguments are 
compatible with their associated parameters. If they are 
not compatible, a specification interrupt may occur. 


RECURSIVE SUBROUTINES AND FUNCTIONS 


PL/I allows an active subroutine or function to invoke 
another procedure and permits a sequence of such invoca- 
tions to proceed to an arbitrary depth. Reinvocation of an 
already active procedure either from within itself or from 
within another active procedure may also occur and forms 
a recursive invocation. The reinvoked procedure is called a 
recursive procedure which must contain the attribute RE- 
CURSIVE in its PROCEDURE statement: 


entry-name: PROCEDURE(parameter-1, . . ..parameter-n) 
RETURNS(result-attribute-list) RECURSIVE; 


Recursion affects variables that possess automatic storage. 
Recursive invocation of a procedure causes the storage for 
each automatic variable within the procedure to be real- 
located and also causes the previously allocated storage to 
be saved automatically in a push-down stack. Termination 
of each activation of a recursive procedure restores the 
most previously allocated storage for the automatic vari- 
ables. 

Recursion does not affect the storage for static vari- 
ables, controlled variables, or based variables. The storage 
and values of such variables remain directly available at all 
levels of recursion. 


Example: 


FACTORIAL: PROCEDURE(N) RETURNS(FIXED 
DECIMAL(6)) RECURSIVE; 


DECLARE N FIXED DECIMAL(2); 
IF N<=1 THEN RETURN(1); 
RETURN(N* FACTORIAL(N-1)); 
END FACTORIAL; 
FACTORIAL is a recursive function procedure that con- 
tains one parameter, N, whose value is a positive integer 
between zero and nine. The function computes the fac- 


torial value of N, which is the product of the integers from 
one to N and which is denoted mathematically by the 
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expression N!. The factorial of three (3!), for example, is 
Six: 


FACTORIAL (3) = 3! = 1-2-3 = 6 
By mathematical convention, the factorial of zero is 
one (0! = 1). Note that the factorial function may be de- 
fined in terms of itself and is, therefore, recursive: 


3! = 3-2! = 3-2-1! =3-2-1=6 


This recursiveness is represented in the FACTORIAL func- 
tion by the following expression: 


N* FACTORIAL(N-1) 


Since this expression appears within the FACTORIAL 
procedure, the reference FACTORIAL(N-1) causes recur- 


sive invocation of FACTORIAL. 


Figure A 1.1 illustrates the flow of program control 
through recursive invocations of the FACTORIAL func- 
tion. To simplify the presentation, the diagram duplicates 
the function procedure at each stage of recursion. It also 
shows the argument value passed by each invocation, the 
flow of control into and out of the function, and the value 
returned by each invoking reference. Since parameter N 
has the automatic storage class, storage is automatically 
allocated for N at each level of recursion, and its value at 
the previous level is saved for reuse when control returns 
to that level. Solid lines in the diagram denote flow of 
control from an invoking reference, and beaded lines repre- 
sent flow of control from a RETURN statement. 

The diagram begins at the top with execution of the 
assignment statement: 


RESULT = FACTORIAL(3); 


Before a value can be assigned to variable RESULT on the 
left, the expression on the right must be evaluated. This 
expression consists of a reference to the FACTORIAL 
function with an argument value of three. When control 
enters the function, storage is allocated for parameter N, 
and it receives the value three. Because N is greater than 
one, the following statement is executed: 


RETURN(N*FACTORIAL(N-1)); 


This statement cannot return control until its expression is 
evaluated. However, the expression itself contains a refer- 
ence to FACTORIAL that causes recursive invocation of 
the function with an argument value of two (3-1 = 2). 






argument 
passed: 
3 






RESULT = 











FACTORIAL: 


PROCEDURE (N) RETURNS(FIXED DECIMAL(6)) 
RECURSIVE; 
DECLARE N FIXED DECIMAL(2); 
IF N<=1 THEN RETURN(1): 


value 






returned: 
3*2=6 






{ RETURNIN * FACTORIAL(N—1)); argument 





passed: 
2 


END FACTORIAL; 





FACTORIAL: 


PROCEDURE (N) RETURNS(FIXED DECIMAL(6)) 
RECURSIVE; 
DECLARE N FIXED DECIMAL(2); 
IF N<=1 THEN RETURN(1); 





value 


returned: 
2*1=2 







{RETURNIN * FACTORIAL(N—1)); argument 





passed: 
1 





END FACTORIAL; 


FACTORIAL: 


PROCEDURE(N) RETURNS(FIXED DECIMAL(6)) 
RECURSIVE; 
DECLARE N FIXED DECIMAL(2); 





value 






returned: 
1 









IF N<(=1 THEN RETURN(1): 
RETURNI(N * FACTORIAL(N—1)): 
END FACTORIAL; 






Figure A1l.1. Computing FACTORIJAL(3) recursively 


This second invocation of FACTORIAL, which is repre- Al.1, the current value (2) of N is saved, and new storage 
sented by the second copy of the function in Figure A 1.1, is allocated for N with a value of one. At this stage of 
causes the current value (3) of N to be saved and new recursion, the value of one for N causes the following 
storage to be allocated for N with a value of two. Again N statement to be executed: 
has a value greater than one, which causes the previous 
RETURN statement to be reexecuted (in the second copy RETURN(1); 


of the function): 
Since this statement does not contain a reference to 


RETURN(N* FACTORIAL(N-1)); FACTORIAL, no further recursion occurs, and control 
returns a value of one to the previous point of invocation. 
Return of control is suspended once more until the expres- The previous point of invocation occurred within the 
sion in the RETURN statement is evaluated. The evalua- second copy of the function and is associated with the 
tion causes a third invocation of FACTORIAL with an statement: 
argument value of one (2-1 = 1). 
When control enters the function for the third time RETURN(N* FACTORIAL(N-1)); 


(represented by the third copy of FACTORIAL in Figure 
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In this statement, N has a value of two, and the value re- 
turned to the reference FACTORIAL(N-1) is one. This 
statement, therefore, returns a value of two (2*1 = 2) to 
the still previous point of invocation, which occurred 
within the first copy of the function and is also associated 
with the following RETURN statement: 


RETURN(N * FACTORIAL(N-1)); 


This time the value of N is three, and the value returned to 
the function reference is two. Hence, this statement re- 
turns a value of six (3*2 = 6) to the previous point of 
invocation, which occurred on the right side of the assign- 
ment statement: 


RESULT = FACTORIAL(3); 


At this point, the value of six for the function reference is 
assigned to variable RESULT. | 

Program T-FACT, shown in Figure Al.2, computes the 
factorial value of all the integers from zero through nine 
and prints the results as shown in Figure A1.3. 


T_FACT:PROCEDURE OPTIONS(MAIN)S$ 
DECLARE 

N FIXED DECIMAL(2), 

RESULT FIXED DECIMAL(6), 

FACTORIAL ENTRY(FIXED DECIMAL(2)) 

RETURNS (FIXED DECIMAL(6))3$ 

PUT LIST(* N FACTORIAL OF N*)35 

PUT SKIP(2);5 

DO N= 0 TO 9 BY 135 
RESULT = FACTORIAL(N)$ 
PUT EDIT(Ny RESULT) (F(2)5 X05), F(6))5 
PUT SKIP3$ 

END; 

FACTORIAL: PROCEDURE(N) 
RETURNS(FIXED DECIMAL (6) )RECURSIVE; 
DECLARE N FIXED DECIMAL(2)35 
IF N <= 1 THEN RETURN(1)35 | 
RETURN(N * FACTORIAL(N —- 1))5 

END FACTORIAL; 

END T_FACT; 


Figure Al.2. Program T_ FACT 
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FACTORIAL OF N 


ON = 


24 

120 
720 
5040 
40320 
362880 


OAN AUR WN PH OO 


Figure Al.3. Printout produced by program T_ FACT 


SUMMARY OF FACILITIES FOR SUBROUTINES AND 
FUNCTIONS 


This summary divides the facilities for subroutines and 
functions into three categories: statements, attributes, and 
invocations. The description of each facility uses standard 
PL/I syntax. Brackets [] denote optional items, and an 
ellipsis . . . specifies optional repetition of the preceding 
item. 

Statements 


entry-name: PROCEDURE |[(parameter 
|,parameter] ...)| 


[RETURNS(result-attribute-list)] [RECURSIVE] ; 
RETURN [(element-expression)] ; 
Attributes 


ENTRY [(parameter-attribute-list | ,parameter- 
attribute-list] .. .)| 


RETURNS (result-attribute-list) 
Invocations 
Subroutine Invocation 
CALL entry-name [(argument[,argument] . . .)]; 
Function Invocation 


entry-name[(argument[,argument] . . .)] 


Appendix 2: Summary of List-Processing Facilities 


The following summary divides the list-processing facilities 
into five categories: attributes, built-in functions, ON- 
conditions, statements, and miscellaneous features. Facil- 
ities within each category appear in alphabetic order. 

When used in the format of each facility, brackets [] 
denote optional items; braces { } indicate that a choice 
must be made from the enclosed items, which are sep- 
arated by an “or” symbol |; and an ellipsis . . . specifies 
optional repetition of the preceding item. 


Attributes 
AREA [{(size-expression) | (*)}] 
BASED(element-pointer-variable) 
OFFSET (area-variable) 
POINTER 


Built-In Functions 
ADDR(argument-variable) 
EMPTY 
NULL 
NULLO 

ON-Condition 
AREA 


Statements 

ALLOCATE based-variable 
[IN(area-variable)] 
{SET(pointer-variable)] 
[ ,based-variable 
[{IN(area-variable) | 
[SET(pointer-variable)]] . . .; 

FREE based-variable 
[IN(area-variable) | 
| ,based-variable 
[IN(area-variable)]] .. .; 

LOCATE based-variable 
FILE(file-name) 
SET(pointer-variable ); 

READ FILE (file-name) 
SET(pointer-variable); 


Miscellaneous Features 
Pointer-qualification symbol: 


—> 


REFER option: 
element-variable REFER (element-variable) 
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